API інтеграція

Повернення коштів може проводитися як щодо всієї суми платежу, так і щодо його частини.

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

An image from the static

Повернення всієї суми платежу (повне повернення)

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

Запит до Financial Line API на повернення може застосовуватися тільки до транзакцій оплати (purchase) або зарахування резерву (capture) з успішними статусами (success).
Використовуйте 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		Refund comment. Can be used for describing reasons of refund 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/refund" \
    -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/"
    }'

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

Parameter	Type	Description
`operation_id`	UUID	Unique Financial Line refund 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	`refund`
`amount`	Number	Actual refund 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	Refund 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":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Повернення частини суми платежу (часткове повернення)

У випадку повернення не всієї суми платежу, а лише його частини запит до Financial Line API повинен містити такі параметри:

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
`refund_amount`	Number	✅	Amount to be refunded. 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		Refund comment. Can be used for describing reasons of refund 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/refund" \
    -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",
      "refund_amount":  80,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/"
    }'

інформація

Cума всіх транзакцій часткового повернення за платежем не може перевищувати загальну суму оригінального платежу.

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

Parameter	Type	Description
`operation_id`	UUID	Unique Financial Line refund 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	`refund`
`amount`	Number	Actual refund 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	Refund 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":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

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

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

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

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

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

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

Додавання платіжних методів

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

Повернення всієї суми платежу (повне повернення)​

Повернення частини суми платежу (часткове повернення)​

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

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

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

Повернення всієї суми платежу (повне повернення)

Повернення частини суми платежу (часткове повернення)

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

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