Платіжні сценарії

API підтримує такі платіжні сценарії:

Одностадійна оплата — негайне списання коштів
Двостадійна оплата — блокування суми з подальшим списанням

Способи інтеграції

Пряма інтеграція (`mode: direct`)

Пряма інтеграція можлива для оплати:

Збереженими картками в гаманці RozetkaPay
Збереженими картками в гаманцях Google Pay та Apple Pay
Платіжними картками — партнер має мати сертифікацію PCI DSS

Взаємодія повністю відбувається через API.

Платіжна сторінка (`mode: hosted`)

Оплата через сторінку RozetkaPay:

Партнер ініціює запит на проведення оплати
У відповідь отримує адресу сторінки для здійснення платежу
Після оплати формується callback зі статусом та деталями операції

Одностадійна оплата

Списання коштів відбувається одразу після успішної авторизації.

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "UAH",
    "external_id": "order_12345",
    "mode": "hosted",
    "confirm": true,
    "callback_url": "https://your-site.com/callback",
    "result_url": "https://your-site.com/result",
    "customer": {
      "email": "user@example.com",
      "phone": "380501234567"
    }
  }'

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

Параметри запиту

Параметр	Обов’язковий	Тип	Опис
`amount`	Так	number	Сума замовлення
`currency`	Так	string	Валюта (ISO 4217), напр. `UAH`
`external_id`	Так	string	Унікальний номер замовлення
`mode`	Так	string	`hosted` — платіжна сторінка; `direct` — дані картки в запиті
`confirm`	Ні	boolean	`true` — списання одразу, `false` — двостадійна
`callback_url`	Ні	string	URL для callback зі статусом
`result_url`	Ні	string	URL для редіректу після оплати
`result_url_success`	Ні	string	URL для редіректу після успішної оплати — має пріоритет над `result_url`
`result_url_fail`	Ні	string	URL для редіректу після неуспішної оплати — має пріоритет над `result_url`
`checkout_ttl`	Ні	number	Скільки хвилин платіжна сторінка лишається доступною
`description`	Ні	string	Опис замовлення (до 2048 символів)
`payload`	Ні	string	Додаткові дані (до 4000 символів)
`init_recurrent_payment`	Ні	boolean	`true` — зберегти `recurrent_id` для рекурентних платежів
`campaign_name`	Ні	string	Валідація типу картки під час оплати. `r_card` — тільки картка Rozetka; `diia_card` — тільки Дія.Картка. Якщо покупець використає інший тип — операція завершиться помилкою

Параметри customer

Параметр	Тип	Опис
`color_mode`	string	`white` або `dark` — тема платіжної сторінки
`locale`	string	`UK`, `EN` або `PL` — мова платіжної сторінки
`email`	string	Email платника
`phone`	string	Телефон платника
`external_id`	string	ID платника у партнера
`first_name`	string	Ім’я
`last_name`	string	Прізвище
`payment_method`	object	Платіжний метод (обов’язковий для `direct`)

Відповідь

{
  "action": {
    "type": "url",
    "value": "https://pay.rozetkapay.com/..."
  },
  "action_required": true,
  "id": "rp_abc123",
  "external_id": "order_12345",
  "is_success": true,
  "details": {
    "status": "init",
    "amount": 100,
    "currency": "UAH",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Параметр	Опис
`action_required`	Чи потрібні додаткові дії
`action.type`	Тип дії (`url` — редірект)
`action.value`	URL для завершення оплати
`is_success`	Успішність операції
`details.status`	Статус операції
`receipt_url`	Посилання на квитанцію (якщо `is_success: true`)

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

Див. окремий гайд: Двостадійна оплата

Статуси операцій

Статус	Опис
`init`	Операція ініційована
`pending`	Очікує обробки
`success`	Успішно завершена
`failure`	Помилка

Повний список статусів і кодів помилок див. у Статусах операцій.