Кошик платежів — RozetkaPay Docs

Кошик платежів дозволяє об’єднати декілька отримувачів коштів (продавців) в один платіж.

Одностадійна оплата (Direct)

Створення кошику

curl -X POST https://api.rozetkapay.com/api/payments/batch/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_external_id": "basket_12345",
    "callback_url": "https://your-site.com/callback",
    "currency": "UAH",
    "confirm": true,
    "mode": "direct",
    "customer": {
      "email": "user@example.com",
      "external_id": "user_123",
      "first_name": "Іван",
      "last_name": "Петренко",
      "phone": "+380501234567",
      "payment_method": {
        "type": "cc_token",
        "cc_token": {
          "token": "tok_card_token"
        }
      }
    },
    "orders": [
      {
        "api_key": "UUID_seller_1",
        "amount": 500,
        "description": "Товар від продавця 1",
        "external_id": "order_001"
      },
      {
        "api_key": "UUID_seller_2",
        "amount": 300,
        "description": "Товар від продавця 2",
        "external_id": "order_002"
      }
    ],
    "result_url": "https://your-site.com/result"
  }'

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

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

Параметр	Обов’язковий	Опис
`batch_external_id`	Так	Унікальний ID кошика
`callback_url`	Так	URL для callback
`currency`	Так	Валюта (UAH)
`confirm`	Ні	`true` — списання одразу, `false` — двостадійна
`mode`	Так	`direct` або `hosted`
`customer`	Так для direct	Дані платника
`orders`	Так	Список замовлень

Параметри замовлення (order)

Параметр	Обов’язковий	Опис
`api_key`	Так	ID проекту продавця
`amount`	Так	Сума замовлення
`description`	Так	Опис замовлення
`external_id`	Так	ID замовлення
`products`	Ні	Список товарів

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

{
  "id": "563338115268219116",
  "action_required": false,
  "batch_details": {
    "amount": "800",
    "auth_code": "294956",
    "currency": "UAH",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "order_details": [
    {
      "external_id": "order_001",
      "amount": "500",
      "status": "success",
      "status_code": "transaction_successful"
    },
    {
      "external_id": "order_002",
      "amount": "300",
      "status": "success",
      "status_code": "transaction_successful"
    }
  ],
  "batch_external_id": "basket_12345"
}

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

curl -X POST https://api.rozetkapay.com/api/payments/batch/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_external_id": "basket_12345",
    "callback_url": "https://your-site.com/callback",
    "currency": "UAH",
    "confirm": true,
    "mode": "hosted",
    "orders": [
      {
        "api_key": "UUID_seller_1",
        "amount": 500,
        "external_id": "order_001"
      },
      {
        "api_key": "UUID_seller_2",
        "amount": 300,
        "external_id": "order_002"
      }
    ],
    "result_url": "https://your-site.com/result",
    "checkout_ttl": 720
  }'

Відповідь

{
  "action_required": true,
  "action": {
    "type": "url",
    "value": "https://buy.rozetkapay.com/order/<UUID>"
  },
  "batch_external_id": "basket_12345"
}

Двостадійна оплата кошику

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

curl -X POST https://api.rozetkapay.com/api/payments/batch/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_external_id": "basket_12345",
    "callback_url": "https://your-site.com/callback",
    "currency": "UAH",
    "confirm": false,
    "mode": "direct",
    "customer": {
      "external_id": "user_123",
      "payment_method": {
        "type": "cc_token",
        "cc_token": {
          "token": "tok_card_token"
        }
      }
    },
    "orders": [
      {
        "api_key": "UUID_seller_1",
        "amount": 500,
        "external_id": "order_001"
      },
      {
        "api_key": "UUID_seller_2",
        "amount": 300,
        "external_id": "order_002"
      }
    ]
  }'

Крок 2: Підтвердження (Confirm)

curl -X POST https://api.rozetkapay.com/api/payments/batch/v1/confirm \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_external_id": "basket_12345",
    "callback_url": "https://your-site.com/callback",
    "currency": "UAH",
    "orders": [
      {
        "api_key": "UUID_seller_1",
        "amount": 500,
        "external_id": "order_001"
      },
      {
        "api_key": "UUID_seller_2",
        "amount": 250,
        "external_id": "order_002"
      }
    ]
  }'

Скасування кошику

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

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

flowchart TD
    P([Платник]) --> CB[Create Batch<br/>confirm: false]
    CB --> H[Блокування коштів]
    H --> CF[Confirm<br/>списання]
    H --> CN[Cancel<br/>скасування]
    CF --> D{Розподіл коштів}
    D --> S1[Продавець 1]
    D --> S2[Продавець 2]
    D --> S3[Продавець 3]
    D --> SN[...]

Callbacks

Callback-и для кошика формуються потранзакційно, не один на весь кошик. Кожне замовлення в кошику отримує окремий callback.