API інтеграція
Цей тип інтеграції дозволяє повернути суму всього спліт-платежу, або провести повне чи часткове повернення окремого субплатежу.
Формат взаємодії:
Повернення всієї суми спліт-платежу (повне повернення)
Особливості використання цієї інтеграції для повернення всієї суми платежу:
- Запит до Tranzzo 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) |
currency | CURRENCY | ✅ | Currency of original order |
refund_amount | Number | ✅ | Amount to be refunded |
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 | |
split | Array[SplitPayment] | ✅ | Split payment properties |
Приклад запиту:
$ curl "https://cpay.tranzzo.com/api/v1/split/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",
"currency": "UAH",
"refund_amount": 100,
"comment": "10101",
"server_url": "https://callback.blackhole.com/callback/capture",
"split":[
{
"amount": 70,
"sub_merchant_id": "${SUB_MERCHANT_ID_1}"
},
{
"amount": 30,
"sub_merchant_id": "${SUB_MERCHANT_ID_2}"
}
]
}'
Параметри відповіді:
Parameter | Type | Description |
---|---|---|
operation_id | UUID | Unique Tranzzo refund identifier |
payment_id | UUID | Tranzzo payment identifier of primary operation |
order_id | String | Merchant's order_id of primary operation (max length is 32 characters) |
transaction_id | UUID | Unique Tranzzo 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 | Tranzzo payment status code |
status_description | STATUS_DESCRIPTION | Tranzzo 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 |
split_fee | Object | Amount and currency of commission by marketplace and sub-merchants |
Приклад відповіді:
{
"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"
}
Повернення субплатежу
За необхідності вся сума субплатежу або окрема його частина може бути повернута. Для проведення такої операції запит повинен містити такі додаткові параметри параметри:
Parameter | Type | Required | Description |
---|---|---|---|
amount | Number | ✅ | Transaction amount |
sub_merchant_id | UUID | ✅ | Unique Sub merchant identifier (to get the identifier, please contact support at [email protected]) |
Важливо
При поверненні кількох субплатежів повинні формуватися окремі запити із зазначенням відповідних субмерчантів.
Наступні кроки
Тестування платіжного процесу:
- Проведіть транзакцію оплати або комбінацію резервування - зарахування резерву, використовуючи автентифікаційні дані тестового проєкту.
- Ініціюйте проведення вторинної операції повернення щодо вищезазначеної транзакції.
- Налаштуйте вебхуки.
- Скористайтеся даними для тестування для отримання різних кодів результатів операцій.
- Опрацьовуйте отримані помилки.
Вихід в онлайн
Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.