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

Структура вебхуків

Загальні положення

Financial Line використовує вебхуки, щоб інформувати вас про всі зміни статусів платежів в режимі реального часу.

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

Ми здійснюємо відправку вебхуків із використанням POST HTTP-методу та таким типом контенту: Content-Type:application/x-www-form-urlencoded

Параметри вебхуків:

ParameterTypeDescription
dataStringBase64Url-encoded JSON
signatureStringdata signed with ${SECRET_KEY}

Приклад вебхука:

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Financial Line відправляє вебхуки з такої IP-адреси:

  • 35.187.74.148
порада

Зазвичай ми здійснюємо відправку на порти 443, 8443 але якщо у вас є потреба у отриманні на інші порти, то повідомте про це Financial Line.

Верифікація вебхуків

Спосіб формування підпису вебхуків: signature=base64url_encode(sha1($API_SECRET + base64url_encode($data) + $API_SECRET))

Функція sha1 повертає необроблені байти замість рядка у шістнадцятковому кодуванні (hex-encoded). Довжина підпису становить 28 символів.

Приклад розрахунку підпису:

raw_data='{"name":"Joe","age":20}'       # {"name":"Joe","age":20}
data='eyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=' # base64url_encode(raw_data)
secret='changeme' # should be changed to ${API_SECRET}

signature='Bcj3hb-h00HrEMIoJ5nPW5ZHlVQ=' # base64url_encode(sha1($secret + $data + secret))

# Bash one-liner:
# 1. calculate sha1 as raw bytes
# 2. encode raw bytes with base64
# 3. replace [+]->[-],[/]->[_]
echo -n 'changemeeyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=changeme' | \
openssl dgst -binary -sha1 | \
base64 | \
tr '/+' '_-'

Параметри вебхуків

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

Параметри вебхуків за первинними операціями (Оплата (purchase), Резервування (auth), Виплата (credit), P2P-перекази (p2p), Перевірка платіжних карток (lookup):

ParameterTypeRequiredDescription
payment_idStringUnique Financial Line payment identifier
order_idStringUnique identifier of order
gateway_order_idStringUnique order identifier in bank acquirer system.
billing_order_idStringUnique Financial Line billing identifier
transaction_idStringUnique Financial Line transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringPayment mode
methodStringPayment method
amountNumberTransaction amount
currencyStringTransaction currency
paywayStringOptional payway
eciStringElectronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
statusStringTransaction status
status_codeStringFinancial Line payment status code
status_descriptionStringFinancial Line payment status code description
cc_maskStringCard number mask
cc_tokenStringFinancial Line card token
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer identifier in merchant's system
customer_phoneStringCustomer phone
feeObjectAmount and currency of commission
fixed_feeObjectAmount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
percent_feeObjectAmount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time
payloadStringPayment request payload

Приклад вебхука за первинною операцією Резервування (auth):

{
"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": 1000,
"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",
"fee": {
"amount": 136,
"currency": "UAH"
},
"percent_fee": {
"amount": 126,
"currency": "UAH"
},
"fixed_fee": {
"amount": 10,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"payload": ""
}

Використання деяких альтернативних платіжних методів передбачає можливість роботи зі змінюваними сумами платежу для тих випадків, коли платник може провести оплату транзакції не у повному обсязі. В такому випадку вебхуки додатково будуть містити такі параметри:

ParameterTypeDescription
processed_amountNumberThe amount that was actually paid by the customer and processed by the payment system. It applies to payments where the final payment amount can be changed by the payer.
processed_currencyString(≤256)Actual currency of payment with processed_amount. It applies to payments where the final payment amount can be changed by the payer.

Приклад вебхука за первинною операцією Оплата (purchase) зі змінюваною сумою:

{
"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": "purchase",
"amount": 1000,
"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",
"fee": {
"amount": 136,
"currency": "UAH"
},
"percent_fee": {
"amount": 126,
"currency": "UAH"
},
"fixed_fee": {
"amount": 10,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"processed_amount": 980,
"processed_currency": "UAH",
"payload": ""
}

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

Параметри вебхуків за операцією Зарахування резерву (capture):

ParameterTypeRequiredDescription
operation_idStringUnique Financial Line capture identifier
payment_idStringFinancial Line payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Financial Line transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringcapture
amountNumberActual capture amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringFinancial Line payment status code
status_descriptionStringFinancial Line payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Приклад:

{
"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.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

Параметри вебхуків за операцією Скасування резерву (void):

ParameterTypeRequiredDescription
operation_idStringUnique Financial Line void identifier
payment_idStringFinancial Line payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Financial Line transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringvoid
amountNumberActual void amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringFinancial Line payment status code
status_descriptionStringFinancial Line payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Приклад:

{
"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": "void",
"amount": 100,
"currency": "UAH",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

Параметри вебхуків за операцією Повернення (refund):

ParameterTypeRequiredDescription
operation_idStringUnique Financial Line refund identifier
payment_idStringFinancial Line payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Financial Line transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringrefund
amountNumberActual refund amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringFinancial Line payment status code
status_descriptionStringFinancial Line payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Приклад:

{
"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": "refund",
"amount": 100,
"currency": "UAH",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

Отримання повторного вебхука за транзакцією

Щоб отримати повторний вебхук за певною транзакцією, треба надіслати запит із використанням GET HTTP-методу.

Параметри запиту:

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}?callback=true" \
-H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
-H "X-API-KEY: ${ENDPOINTS_KEY}"

Query параметри:

ParameterTypeRequiredDescription
callbackBooleantrue
інформація

Зверніть увагу, окрім вищенаведених параметрів вебхуки можуть містити додаткову інформацію. Щоб дізнатися про додаткові параметри, що можуть включатися до вебхуків, та налаштувати їх передачу зверніться до Служби підтримки Financial Line.

Отримання повторного вебхука за регулярними платежами

Для отримання повторного вебхуку за регулярними платежами, надішліть GET-запит до ендпоїнту /api/v1/pos/:posId/orders/:orderId/purchase?callback=true&transactionId=:paymentId, де: posId - ID проекту мерчанта, orderId - ID замовлення, transactionId - ID транзакції.

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

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

Опційні query-параметри запиту:

ParameterTypeRequiredDescription
callbackBooleantrue
transactionIdStringAn identifier for one of the transactions within the corresponding recurring payment

Якщо запит не містить query-параметру transactionId, то у відповідь буде отримано дані за останньою транзакцією відповідної підписки.

Приклад запиту за певною транзакцією:

curl "https://api.finline.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/purchase?callback=true&transactionId=${TRANSACTION_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",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"payload": ""
},
"recurring": {
"id": "n9W9kyytX2q62jBg7fu7V",
"status": "active"
},