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

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

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

1. Клієнт оформлює замовлення
2. Кошти блокуються на карті (hold)
3. Магазин підтверджує наявність товару
4. Списання коштів (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"
    }
  }'

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

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

{
  "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"
  }'

Параметри 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"
  }'

Параметри cancel

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

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

{
  "is_success": true,
  "details": {
    "status": "success",
    "status_code": "1009",
    "status_description": "Reverse successful"
  }
}

Обмеження

Обережно

• Сума списання не може перевищувати суму блокування
• Валюта має співпадати
• Списання можливе до 30 днів від моменту блокування

Приклад повного флоу

// 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
  })
});

Діаграма процесу

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Клієнт    │────▶│  Create      │────▶│  Блокування │
│             │     │  confirm:    │     │   коштів    │
│             │     │  false       │     │             │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                │
                    ┌───────────────────────────┼───────────────────────────┐
                    │                           │                           │
                    ▼                           ▼                           ▼
            ┌──────────────┐           ┌──────────────┐            ┌──────────────┐
            │   Confirm    │           │    Cancel    │            │  Timeout     │
            │  (списання)  │           │ (розблокув.) │            │  (30 днів)   │
            └──────────────┘           └──────────────┘            └──────────────┘