Двостадійна оплата

Двостадійна оплата дозволяє попередньо заблокувати кошти на рахунку користувача, а потім списати їх або розблокувати.

Сценарій використання

Клієнт оформлює замовлення
Кошти блокуються на картці (hold)
Магазин підтверджує наявність товару
Списання коштів (capture) або розблокування (cancel)

Крок 1: Блокування коштів

Створіть платіж з параметром confirm: false:

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "UAH",
    "external_id": "order_12345",
    "mode": "hosted",
    "confirm": false,
    "callback_url": "https://your-site.com/callback",
    "result_url": "https://your-site.com/result",
    "description": "Замовлення #12345",
    "customer": {
      "email": "user@example.com",
      "phone": "380501234567"
    }
  }'

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

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

При успішному блокуванні:

{
  "is_success": true,
  "details": {
    "status": "success",
    "status_code": "transaction_successful",
    "status_description": "Protected transaction. Amount was successfully blocked"
  }
}

Крок 2: Списання коштів (Confirm)

Для списання заблокованих коштів:

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

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

Параметри confirm

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

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

Можна списати меншу суму, ніж була заблокована:

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

Альтернатива: Розблокування коштів (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 →

Параметри cancel

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

Успішне розблокування

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

Обмеження

Приклад повного процесу

// 1. Створення замовлення з блокуванням
const createResponse = await fetch("https://api.rozetkapay.com/api/payments/v1/new", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa("login:password"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 1500,
    currency: "UAH",
    external_id: "order_789",
    mode: "hosted",
    confirm: false,
    callback_url: "https://your-site.com/callback",
  }),
});

// 2. Редірект на платіжну сторінку
const { action } = await createResponse.json();
window.location.href = action.value;

// 3. Після отримання callback про успішне блокування — підтвердження
const confirmResponse = await fetch("https://api.rozetkapay.com/api/payments/v1/confirm", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa("login:password"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "order_789",
    amount: 1500,
  }),
});