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

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

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

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

Host2Host (Direct)

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

Оплати збереженими картками
Гаманців Google Pay та Apple Pay
Оплати платіжними картками (потрібен PCI DSS сертифікат)

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

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

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

Параметр	Обов’язковий	Тип	Опис
`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 для редіректу після оплати
`description`	Ні	string	Опис замовлення (до 2048 символів)
`payload`	Ні	string	Додаткові дані (до 4000 символів)

Параметри customer

Параметр	Тип	Опис
`color_mode`	string	`light` або `dark` — тема чекаута
`locale`	string	`UK`, `EN`, `ES`, `PL`, `FR`, `SK`, `DE`
`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`)

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

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

P2P перекази

Див. окремий гайд: P2P перекази

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

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

Повний список статусів див. у API Reference.