Перейти до основного вмісту

Отримання інформації про платежі

Після того, як платежі було проведено, ви можете отримати інформацію про них з таким рівнем конкретизації:

  • Інформація про конкретну транзакцію в межах одного замовленням.
  • Інформації про всі транзакції конкретного замовлення.
  • Інформація про всі транзакції, що мали місце за певний період часу.
  • Реєстр транзакцій у JSON-форматі.

Інформація щодо транзакції

Для отримання інформації про конкретну транзакцію в межах одного замовлення необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

ParameterTypeRequiredDescription
POS_IDUUIDMerchant's identifier (POS_ID)
ORDER_IDStringMerchant's order identifier
OPERATIONStringPayment method, e.g. purchase, void, etc.

Приклад запиту на отримання інформації про транзакцію:

$ 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_ID) необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

ParameterTypeRequiredDescription
POS_IDStringMerchant's identifier (POS_ID)
ORDER_IDStringMerchant's order identifier

Приклад запиту на отримання інформації про всі транзакції замовлення:

$ 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}"

Відповідь на такий запит буде містити масив транзакцій, що пов’язані з відповідним замовленням.

Приклад відповіді за двостадійними платежами:

[
{
"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"
}
]

Приклад відповіді за регулярними платежами:

{
"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"
}

Аналогічно можна отримати інформацію про транзакції за підпискою на регулярні платежі. Для цього треба відправити GET-запит до ендпоїнту /api/v1/pos/:posId/recurring/:recurringId, де recurringId - унікальний ID підписки.

До запиту також можуть входити такі query-параметри:

ParameterRequiredDescription
methodPayment methods (only purchase or refund value is accepted)
statusTransaction status

Інформація про транзакції за певний період

Для отримання інформації про всі транзакції, що було проведено за певний період часу, необхідно сформувати запит з HTTP-методом GET та таким набором параметрів:

Path-параметри:

ParameterTypeRequiredDescription
POS_IDUUIDMerchant's identifier (POS_ID)

Query-параметри:

ParameterTypeRequiredDescription
startDateNumberTime from - UNIX timestamp
enddateNumberTime to - UNIX timestamp

Приклад запиту:

$ 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}"

Дата у запиті має бути у форматі Unix time. Наприклад:

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

Відповідь на такий запит буде містити масив транзакцій за вказаний період.

Приклад відповіді:

{"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":""}

Реєстр транзакцій у JSON-форматі

За необхідності можна отримати реєстр JSON форматі з транзакціями, відфільтрованиим за часом, статусом та методом. Реєстр міститиме вказані у запиті деталі кожного платежу.

Для формування реєстру транзакцій необхідно сформувати запит з HTTP-методом POST та таким набором параметрів:

ParameterRequiredDescription
project_idMerchant's identifier (POS_ID)
start_dateThe start date of the period for which the data is required
end_datePeriod end date. The maximum period is 31 days
statusesArray of Transaction status
methodsPayment methods (auth, purchase, capture, void, p2p, credit, lookup, refund, dispute, recurrent)
transaction_detailsArray field with the parameters that are received for each of the transactions in report

Окрім того, для такого реєстру можна задати конкретний набір параметрів деталей платежу, які ви бажаєте отримати:

ParameterDefaultDescription
orderIdMerchant's order identifier to be captured
paymentIdFinancial Line payment identifier of primary operation
amountTransaction amount with fees applied
currencyTransaction currency
methodPayment methods
statusTransaction status
dateTimeTransaction date
cardMaskСard mask
paywayPayway name
customerFeeCustomer fee
merchantFeeMerchant fee
entityNameEntity name
projectNameProject name
originalAmountTransaction amount with no fees applied
exchangeAmountExchange amount
exchangeCurrencyExchange currency
exchangeRateExchange rate
tokenizationKindTokenization kind
authCodeTransaction authentication code
rrnCodeRRN code
descriptionTransaction description
payloadField for custom data
paymentSystemPayment system
recipientCardMaskRecipient's card mask
reserveAmountRolling reserve amount
receiverNameName of sub merchant in split transaction
receiverAmountAmount paid to sub merchant in split transaction
receiverFeeFee amount paid by sub merchant in split transaction
інформація

Зверніть увагу, якщо ви не включите до запиту перелік параметрів, інформація за якими має бути в реєстрі транзакцій, то реєстр буде сформовано з тими параметрами, що відмічені за замовчуванням.

Отримання реєстру транзакцій відбувається у два етапи:

  1. Запит на отримання ідентифікатору згенерованого реєстру.
  2. Запит на отримання самого реєстру у форматі JSON з використанням попередньо отриманого ідентифікатора.

Приклад запиту на формування реєстру транзакцій:

$ 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"
]
}'

Параметри відповіді:

ParameterDescription
report_idJSON file identifier
countnumber of records (transactions)

Приклад відповіді:

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

Приклад відповіді у випадку, коли реєстр ще не сформовано:

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

Для отримання сформованого реєстру транзакцій у JSON-форматі необхідно відправити запит з HTTP-методом GET з отриманим ідентифікатором реєстру report_id.

Приклад запиту:

$ 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'

Відповідь на запит буде містити JSON з кількістю записів, що дорівнює отриманому у параметрі count значенню. Кожен запис містить набір параметрів, вказаних при формуванні реєстру транзакцій, або параметрів за замовчуванням.

Приклад відповіді:

{"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":""}