Отримання інформації про платежі
Після того, як платежі було проведено, ви можете отримати інформацію про них з таким рівнем конкретизації:
- Інформація про конкретну транзакцію в межах одного замовленням.
- Інформації про всі транзакції конкретного замовлення.
- Інформація про всі транзакції, що мали місце за певний період часу.
- Реєстр транзакцій у JSON-форматі.
Інформація щодо транзакції
Для отримання інформації про конкретну транзакцію в межах одного замовлення необхідно сформувати запит з HTTP-методом GET
та таким набором параметрів:
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. |
Приклад запиту на отримання інформації про транзакцію:
$ 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
та таким набором параметрів:
Parameter | Type | Required | Description |
---|---|---|---|
POS_ID | String | ✅ | Merchant's identifier (POS_ID ) |
ORDER_ID | String | ✅ | Merchant'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-параметри:
Parameter | Required | Description |
---|---|---|
method | ✅ | Payment methods (only purchase or refund value is accepted) |
status | ✅ | Transaction status |
Інформація про транзакції за певний період
Для отримання інформації про всі транзакції, що було проведено за певний період часу, необхідно сформувати запит з HTTP-методом GET
та таким набором параметрів:
Path-параметри:
Parameter | Type | Required | Description |
---|---|---|---|
POS_ID | UUID | ✅ | Merchant's identifier (POS_ID ) |
Query-параметри:
Parameter | Type | Required | Description |
---|---|---|---|
startDate | Number | ✅ | Time from - UNIX timestamp |
enddate | Number | ✅ | Time 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
та таким набором параметрів:
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 |
Окрім того, для такого реєстру можна задати конкретний набір параметрів деталей платежу, які ви бажаєте отримати:
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 |
Зверніть увагу, якщо ви не включите до запиту перелік параметрів, інформація за якими має бути в реєстрі транзакцій, то реєстр буде сформовано з тими параметрами, що відмічені за замовчуванням.
Отримання реєстру транзакцій відбувається у два етапи:
- Запит на отримання ідентифікатору згенерованого реєстру.
- Запит на отримання самого реєстру у форматі 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"
]
}'
Параметри відповіді:
Parameter | Description |
---|---|
report_id | JSON file identifier |
count | number 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":""}