Getting transaction information

Once transactions have been processed, you can retrieve information about them at different levels of detail, including:

Details on a specific transaction within an order.
Information about all transactions associated with a specific order.
Information about all transactions that took place during a specific time period.
A transaction register in JSON format.

Details about a specific transaction

To obtain information about a specific transaction within an order, you need to send a request with the GET HTTP method and include the following set of parameters:

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier
`OPERATION`	String	✅	Payment method, e.g. `purchase`, `void`, etc.

Here's an example of a request to obtain information about a transaction:

$ curl "https://api.finline.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/${OPERATION}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Order and subscription information

If you want to receive information about all transactions associated with a specific order (ORDER_ID), you need to send a request with the GET HTTP method and include the following set of parameters:

Parameter	Type	Required	Description
`POS_ID`	String	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier

Here's an example of a request to obtain information about all transactions of an order:

$ curl "https://api.finline.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

When you send a request for transaction information associated with a specific order, the corresponding response will include an array of transactions linked to that order.

Here is an example response for two-step payments:

[
  {
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":            "111999991",
    "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
    "billing_order_id":    "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                "direct",
    "method":              "auth",
    "amount":              0.28,
    "currency":            "UAH",
    "payway":              "...",
    "eci":                 "7",
    "status":              "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "cc_mask":             "424242******4242",
    "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
    "cc_token_expiration": "2020-10-10T10:10:22",
    "customer_id":         "123",
    "customer_phone":      "+380999999999",
    "created_at":          "2018-10-10T10:10:10.100",
    "processing_time":     "2018-10-10T10:10:22.100",
    "payload":             "",
    "bank_short_name":     "Bank name"
  },
  {
    "operation_id":          "edf7605c-99a8-43be-a1a5-2e96ebac8512",
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":              "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":                "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                  "direct",
    "method":                "capture",
    "amount":                100,
    "currency":              "UAH",
    "status":                "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "created_at":          "2018-10-10T10:11:11.100",
    "processing_time":     "2018-10-10T10:11:12.000"
  }
]

Response example for recurring payments

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "success",
  "status_code":          "1000",
  "status_description": "Transaction is successful",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
   "recurring": {
                         "id": "r7dAMIRmS~3nCiHVFpSC8",
                         "status": "init"
   },
  "result_url":          "https://example.com/result",
  "created_at":          "2023-09-14T14:08:13.509",
  "processed_at":        "2023-09-14T14:08:16.112",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Similarly, you can get information about transactions of a subscription for recurring payments. In order to do so, send a GET request to the /api/v1/pos/:posId/recurring/:recurringId endpoint, where the value of the recurringId parameter should be the unique ID associated with the corresponding recurring payment subscription.

Parameter	Required	Description
`method`	✅	Payment methods (only `purchase` or `refund` value is accepted)
`status`	✅	Transaction status

Information on all transactions over a specific time period

To obtain information about all transactions carried out within a specific time frame, you need to create a request with the GET HTTP method and the following set of parameters:

Path parameters:

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)

Query parameters:

Parameter	Type	Required	Description
`startDate`	Number	✅	Time from - UNIX timestamp
`enddate`	Number	✅	Time to - UNIX timestamp

Request example:

$ curl "https://api.finline.io/api/v1/pos/${POS_ID}/transactions?startDate=${startDate}&enddate=${enddate}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

The date included in the request should be in Unix time format, for instance:

/api/v1/pos/${POS_ID}/transactions?startDate=1670120382000&enddate=1683721382000

The server will return an array of transactions that occurred during the requested period.

Response example:

{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"630428489","paymentId":"84f32e8c-6919-49c5-8353-25f6f7c4f371","amount":"1.00","currency":"UAH","method":"purchase","status":"pending","dateTime":"","authCode":"","rrnCode":"","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"","recipientCardMask":""}
{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"288558688","paymentId":"620694b9-8e49-42b7-b3cb-950b80529861","amount":"1.00","currency":"UAH","method":"purchase","status":"failure","dateTime":1683646963767,"authCode":"","rrnCode":"","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"VISA","recipientCardMask":""}
{"projectId":"2a810802-d3ac-4aad-b4c7-74c54cba628e","orderId":"1369031473","paymentId":"5ee8fb17-f0ec-4e2f-823f-8ffa205f0d7b","amount":"1.00","currency":"UAH","method":"purchase","status":"success","dateTime":1683646725585,"authCode":"","rrnCode":"4428573","description":"test description","payload":"","customerFee":"0.00","merchantFee":"1.07","paymentSystem":"DISCOVER","recipientCardMask":""}

Transaction register in JSON format

You can also obtain a transaction register in JSON format filtered by time, status, and method, which includes the details of each payment specified in the request.

To generate a transaction register, you need to send a request using the POST HTTP method and the following set of parameters:

Parameter	Required	Description
`project_id`	✅	Merchant's identifier (`POS_ID`)
`start_date`	✅	The start date of the period for which the data is required
`end_date`	✅	Period end date. The maximum period is 31 days
`statuses`		Array of Transaction status
`methods`		Payment methods (`auth`, `purchase`, `capture`, `void`, `p2p`, `credit`, `lookup`, `refund`, `dispute`, `recurrent`)
`transaction_details`		Array field with the parameters that are received for each of the transactions in report

Furthermore, you can specify a particular set of payment detail parameters that you want to include in the registry:

Parameter	Default	Description
`orderId`	✅	Merchant's order identifier to be captured
`paymentId`	✅	Financial Line payment identifier of primary operation
`amount`	✅	Transaction amount with fees applied
`currency`	✅	Transaction currency
`method`	✅	Payment methods
`status`	✅	Transaction status
`dateTime`	✅	Transaction date
`cardMask`	✅	Сard mask
`payway`	✅	Payway name
`customerFee`	✅	Customer fee
`merchantFee`	✅	Merchant fee
`entityName`		Entity name
`projectName`		Project name
`originalAmount`		Transaction amount with no fees applied
`exchangeAmount`		Exchange amount
`exchangeCurrency`		Exchange currency
`exchangeRate`		Exchange rate
`tokenizationKind`		Tokenization kind
`authCode`		Transaction authentication code
`rrnCode`		RRN code
`description`		Transaction description
`payload`		Field for custom data
`paymentSystem`		Payment system
`recipientCardMask`		Recipient's card mask
`reserveAmount`		Rolling reserve amount
`receiverName`		Name of sub merchant in split transaction
`receiverAmount`		Amount paid to sub merchant in split transaction
`receiverFee`		Fee amount paid by sub merchant in split transaction

info

Note: if you do not include a list of parameters that should be in the transaction register, the register will be created with default parameters.

Obtaining the transaction register involves two stages:

Send a request to obtain the identifier of the generated registry.
Send another request to obtain the transaction register itself in JSON format using the previously obtained identifier.

Here's an example request to create a transaction register:

$ curl --location --request POST 'https://api.finline.io/streaming-report/start' \
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "064ec3f8-8abb-414b-9eb3-49d977213967",
    "start_date": "2022-09-01T12:00:03.007+00:00",
    "end_date": "2022-09-30T23:58:03.007+00:00",
    "statuses": [ "success", "pending", "failure", "init" ],
    "methods": [
        "purchase",
        "auth",
        "capture",
        "void",
        "p2p",
        "credit",
        "lookup",
        "refund",
        "dispute"
        ],
    "transaction_details": [
       "projectId",
       "orderId",
       "paymentId",
       "amount",
       "currency",
       "method",
       "status",
       "dateTime",
       "cardMask",
       "payway",
       "entityName",
       "projectName",
       "originalAmount",
       "exchangeAmount",
       "exchangeCurrency",
       "exchangeRate",
       "tokenizationKind",
       "authCode",
       "rrnCode",
       "description",
       "payload",
       "customerFee",
       "merchantFee",
       "paymentSystem",
       "recipientCardMask"
    ]
}'

Response parameters:

Parameter	Description
`report_id`	JSON file identifier
`count`	number of records (transactions)

Response example:

{"report_id":"57e79df2-b374-4998-9b0e-ac7848760bed","count":384}

An example of a response in a case when the register has not yet been generated:

{
  "message": "Report not ready",
  "code": "report_not_ready"
}

To retrieve the generated transaction registry in JSON format, you need to submit a request using the GET HTTP method with the report_id parameter containing the received registry identifier.

Request example:

$ curl --location --request GET 'https://api.finline.io/streaming-report/fetch/57e79df2-b374-4998-9b0e-ac7848760bed'
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq'

The JSON response to the request will include the number of records specified in the count parameter. Each record will contain a set of parameters that were defined when the transaction register was generated, or default parameters if none were specified.

Response example:

{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213999","orderId":"1456649508235","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb58","amount":"3","currency":"UAH","method":"void","status":"success","dateTime":1662033684016,"cardMask":"414141******2284","payway":"applepay","entityName":"","projectName":"Project","originalAmount":"3","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213988","orderId":"1456649508236","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb51","amount":"2","currency":"UAH","method":"auth","status":"success","dateTime":1662033684916,"cardMask":"537541******2284","payway":"gpay","entityName":"","projectName":"Project","originalAmount":"2","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb2-49d977213967","orderId":"1456649508238","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb50","amount":"1","currency":"UAH","method":"purchase","status":"success","dateTime":1662033680916,"cardMask":"537541******1184","payway":"cc","entityName":"","projectName":"Test Project","originalAmount":"1","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"test qa","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}

Details about a specific transaction​

Order and subscription information​

Information on all transactions over a specific time period​

Transaction register in JSON format​

Details about a specific transaction

Order and subscription information

Information on all transactions over a specific time period

Transaction register in JSON format