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

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

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

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

curl -X POST https://api.rozetkapay.com/api/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"
  }'

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

Параметр	Обов’язковий	Опис
`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"
  },
  "orders_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 (Hosted)

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

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

┌─────────────────┐
│    Платник      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  Create Batch   │────▶│   Блокування    │
│  confirm: false │     │     коштів      │
└─────────────────┘     └────────┬────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Confirm       │     │    Cancel       │     │    Timeout      │
│  (списання)     │     │  (скасування)   │     │   (7 днів)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Розподіл коштів                              │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐    │
│  │ Продавець │  │ Продавець │  │ Продавець │  │    ...    │    │
│  │     1     │  │     2     │  │     3     │  │           │    │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘    │
└─────────────────────────────────────────────────────────────────┘

Callbacks

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