Повернення коштів

Типи операцій

Операція	Коли використовувати
Refund	Після успішного списання коштів
Cancel	Для скасування заблокованих (холд) коштів

Повернення коштів (Refund)

Повернення коштів після успішного платежу:

curl -X POST https://api.rozetkapay.com/api/payments/v1/refund \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "amount": 100,
    "currency": "UAH",
    "callback_url": "https://your-site.com/callback"
  }'

Весь перелік полів — у API Reference →

Параметри

Параметр	Обов’язковий	Опис
`external_id`	Так	ID оригінального замовлення
`amount`	Ні	Сума повернення (якщо не вказано — повна сума)
`currency`	Ні	Валюта
`callback_url`	Ні	URL для callback
`payload`	Ні	Додаткові дані

Успішна відповідь

{
  "is_success": true,
  "details": {
    "status": "success",
    "status_code": "refund_successful",
    "status_description": "Refund successful."
  }
}

Часткове повернення

Можна повернути частину суми:

curl -X POST https://api.rozetkapay.com/api/payments/v1/refund \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "amount": 50,
    "currency": "UAH"
  }'

Відкладене повернення

Повернення списується з балансу партнера, тому суми на ньому має бути достатньо. Баланс партнера — це загальна сума сьогоднішніх платежів до виплати.

Якщо коштів не вистачає, повернення переходить у статус «в обробці» і виконується автоматично, коли баланс досягне суми повернення.

Відповідь на такий запит:

{
  "is_success": false,
  "details": {
    "status": "pending",
    "status_code": "refund_pending",
    "status_description": "Refund is pending due to insufficient balance"
  }
}

Примусове повторення

Щоб вручну повторити спробу повернення:

curl -X POST https://api.rozetkapay.com/api/payments/v1/refund/retry \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345"
  }'

Відміна відкладеного повернення

Щоб скасувати pending повернення:

curl -X POST https://api.rozetkapay.com/api/payments/v1/refund/cancel \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345"
  }'

Статус зміниться на refund_is_cancelled_by_initiator.

Скасування холду (Cancel)

Для розблокування раніше заблокованих коштів (двостадійна оплата):

curl -X POST https://api.rozetkapay.com/api/payments/v1/cancel \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "callback_url": "https://your-site.com/callback"
  }'

Весь перелік полів — у API Reference →

Часткове скасування

curl -X POST https://api.rozetkapay.com/api/payments/v1/cancel \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "amount": 50,
    "currency": "UAH"
  }'

Успішна відповідь

{
  "is_success": true,
  "details": {
    "status": "success",
    "status_code": "cancel_successful",
    "status_description": "Cancel successful."
  }
}

Коли що використовувати

Сценарій	Операція
Товар не підійшов (після оплати)	`refund`
Замовлення скасовано до відправки (двостадійна)	`cancel`
Клієнт відмовився до списання	`cancel`
Товар пошкоджений (після оплати)	`refund`

Статуси повернень

Статус	Опис
`refund_successful`	Успішне повернення
`refund_pending`	Очікує (недостатньо коштів)
`refund_is_cancelled_by_system`	Скасовано системою
`refund_is_cancelled_by_initiator`	Скасовано мерчантом

Callbacks

Після кожної операції повернення надсилається callback. Нижче — повне тіло callback, яке надходить на ваш callback_url. Весь перелік полів — у API Reference.

{
  "id": "rp_abc123",
  "external_id": "order_12345",
  "operation": "refund",
  "is_success": true,
  "details": {
    "payment_id": "563338115268219116",
    "status": "success",
    "status_code": "refund_successful",
    "status_description": "Refund successful.",
    "amount": "100",
    "currency": "UAH",
    "created_at": "2024-01-15T10:30:00Z",
    "processed_at": "2024-01-15T10:30:05Z",
    "method": "refund"
  }
}