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

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

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

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

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

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

Parameter	Type	Description
`data`	String	Base64Url-encoded JSON
`signature`	String	`data` 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):

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique Financial Line payment identifier
`order_id`	String	✅	Unique identifier of order
`gateway_order_id`	String		Unique order identifier in bank acquirer system.
`billing_order_id`	String		Unique Financial Line billing identifier
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	Payment mode
`method`	String	✅	Payment method
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency
`payway`	String		Optional payway
`eci`	String		Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		Financial Line card token
`cc_token_expiration`	String		Token expiration timestamp
`customer_id`	String		Customer identifier in merchant's system
`customer_phone`	String		Customer phone
`fee`	Object		Amount and currency of commission
`fixed_fee`	Object		Amount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
`percent_fee`	Object		Amount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time
`payload`	String		Payment 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":             ""
}

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

Parameter	Type	Description
`processed_amount`	Number	The 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_currency`	String(≤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):

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line capture identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`capture`
`amount`	Number	✅	Actual capture amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp 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):

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line void identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`void`
`amount`	Number	✅	Actual void amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp 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):

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line refund identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`refund`
`amount`	Number	✅	Actual refund amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp 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-методу.

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

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

Query параметри:

Parameter	Type	Required	Description
`callback`	Boolean	✅	`true`

інформація

Зверніть увагу, окрім вищенаведених параметрів вебхуки можуть містити додаткову інформацію. Щоб дізнатися про додаткові параметри, що можуть включатися до вебхуків, та налаштувати їх передачу зверніться до Служби підтримки 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-параметри запиту:

Parameter	Type	Required	Description
`callback`	Boolean	✅	`true`
`transactionId`	String		An 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"
},

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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