API інтеграція

Цей тип інтеграції дозволяє проводити вторинні операції із зарахування всієї суми резерву або його частини.

Формат взаємодії:

Зарахування всієї суми резерву

Особливості використання цієї інтеграції для зарахування повної суми резерву:

1. Запит до Financial Line API на зарахування резерву може застосовуватися тільки до первинних операцій резервування (auth) з успішним статусом (success).
2. Використовуйте HTTP-метод POST.

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

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
order_id	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
order_currency	CURRENCY	✅	Currency of original order
comment	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
server_url	URL		Webhook notification will be sent to this URL

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

$ curl "https://api.finline.io/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

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

Parameter	Type	Description
operation_id	UUID	Unique Financial Line capture identifier
payment_id	UUID	Financial Line payment identifier of primary operation
order_id	String	Merchant's order_id of primary operation (max length is 32 characters)
transaction_id	UUID	Unique Financial Line transaction identifier
pos_id	UUID	Merchant's identifier (POS_ID)
mode	MODE	direct
method	METHOD	capture
amount	Number	Actual captured amount
order_currency	CURRENCY	Transaction currency
status	STATUS	Transaction status
status_code	STATUS_CODE	Financial Line payment status code
status_description	STATUS_DESCRIPTION	Financial Line payment status code description
created_at	TIMESTAMP	Timestamp when transaction was created
processing_time	TIMESTAMP	Timestamp when transaction was updated last time
fee	Object	Amount and currency of commission
comment	String	Capture comment

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

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "order_currency":       "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Зарахування частини суми резерву

Формат взаємодії:

У випадку зарахування не всієї суми резерву, а лише його частини у запиті додатково також має передаватися обов’язковий параметр: charge_amount Number

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

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
order_id	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
order_currency	CURRENCY	✅	Currency of original order
charge_amount	Number	✅	Amount to be captured. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
comment	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
server_url	URL		Webhook notification will be sent to this URL

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

$ curl "https://api.finline.io/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "charge_amount":  80,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

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

Parameter	Type	Description
operation_id	UUID	Unique Financial Line capture identifier
payment_id	UUID	Financial Line payment identifier of primary operation
order_id	String	Merchant's order_id of primary operation (max length is 32 characters)
transaction_id	UUID	Unique Financial Line transaction identifier
pos_id	UUID	Merchant's identifier (POS_ID)
mode	MODE	direct
method	METHOD	capture
amount	Number	Actual captured amount
currency	CURRENCY	Transaction currency
status	STATUS	Transaction status
status_code	STATUS_CODE	Financial Line payment status code
status_description	STATUS_DESCRIPTION	Financial Line payment status code description
created_at	TIMESTAMP	Timestamp when transaction was created
processing_time	TIMESTAMP	Timestamp when transaction was updated last time
fee	Object	Amount and currency of commission
comment	String	Capture comment

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

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Зарахування понад суму резерву

Формат взаємодії (залежно від інтеграції):

Варіант 1:

Варіант 2:

При використанні функціоналу зарахування понад суму резерву, при ініціації транзакції зарахування резерву в параметрі charge_amount слід передати суму, що має бути зараховано.

Важливо

Вказана сума не може перевищувати відсоток, встановлений у налаштуваннях вашого проєкту на стороні Financial Line.

Наступні кроки

Тестування платіжного процесу:

• Проведіть первинну операцію із резервування, використовуючи автентифікаційні дані тестового проєкту
• Ініціюйте проведення вторинної операції із зарахування резерву щодо первинної операції
• Налаштуйте вебхуки
• Скористайтеся даними для тестування для отримання різних кодів результатів операцій
• Опрацьовуйте отримані помилки.

Вихід в онлайн

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

Дивіться також:

• Скасування резерву
• Додавання платіжних методів