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

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

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

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

Ми здійснюємо відправку вебхуків із використанням 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

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

35.187.74.148

порада

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

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

Спосіб формування підпису вебхуків: 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 '/+' '_-'

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

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

інформація

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

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

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique AI Fintech 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 AI Fintech billing identifier
`transaction_id`	String		Unique AI Fintech 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		AI Fintech payment status code
`status_description`	String		AI Fintech payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		AI Fintech 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
`receipt_url`	URL		URL link to the receipt for the corresponding transaction. Available for primary transactions such as `purchase`, `auth`, and `credit`

Приклад вебхука за первинною операцією Резервування (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":             "",
  "receipt_url":         "https://api.aifintech.ua/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

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

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 AI Fintech capture identifier
`payment_id`	String	✅	AI Fintech payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique AI Fintech 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		AI Fintech payment status code
`status_description`	String		AI Fintech 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 AI Fintech void identifier
`payment_id`	String	✅	AI Fintech payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique AI Fintech 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		AI Fintech payment status code
`status_description`	String		AI Fintech 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 AI Fintech refund identifier
`payment_id`	String	✅	AI Fintech payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique AI Fintech 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		AI Fintech payment status code
`status_description`	String		AI Fintech 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
`receipt_url`	URL		URL link to the receipt for the corresponding transaction

Приклад:

{
  "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",
  "receipt_url":         "https://api.aifintech.ua/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

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

Щоб отримати повторний вебхук за певною транзакцією, треба надіслати запит із використанням 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.aifintech.ua/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`

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

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

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

curl "https://api.aifintech.ua/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.aifintech.ua/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):

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

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