Виплати

Виплати (Payouts) дозволяють переказувати кошти з балансу мерчанта на картки отримувачів.

Створення виплати на картку

curl -X POST https://api.rozetkapay.com/api/payouts/v1/request-payout \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "external_id": "payout_12345",
      "original_amount": "1000",
      "currency": "UAH",
      "description": "Виплата за замовлення",
      "callback_url": "https://your-site.com/payout-callback"
    },
    "payer": {
      "entity_id": "your_entity_id"
    },
    "recipient": {
      "payout_type": "card",
      "card": {
        "first_name": "Іван",
        "last_name": "Петренко",
        "card_data": {
          "number": "4242424242424242"
        }
      }
    }
  }'

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

order (обов’язкове)

Параметр	Обов’язковий	Опис
`external_id`	Так	Унікальний ID виплати
`original_amount`	Так	Сума виплати (string)
`currency`	Так	Валюта (UAH)
`description`	Так	Опис виплати (до 500 символів)
`callback_url`	Ні	URL для callback

payer (обов’язкове)

Параметр	Обов’язковий	Опис
`entity_id`	Так	ID сутності платника

recipient (обов’язкове)

Параметр	Обов’язковий	Опис
`payout_type`	Так	Тип виплати: `card` або `cash`
`card`	Для card	Дані картки отримувача
`cash`	Для cash	Дані для готівкової виплати

card (для payout_type: card)

Параметр	Обов’язковий	Опис
`first_name`	Так	Ім’я отримувача
`last_name`	Так	Прізвище отримувача
`middle_name`	Ні	По батькові
`email`	Ні	Email отримувача
`phone`	Ні	Телефон (+380…)
`ipn`	Ні	ІПН (10 цифр)
`card_data`	Так	Дані картки

card_data

Параметр	Опис
`number`	Повний номер картки (якщо немає token)
`token`	Токен картки з попередньої операції (якщо немає number)
`option_id`	ID картки з гаманця

Відповідь

{
  "id": "payout_abc123",
  "external_id": "payout_12345",
  "status": "pending",
  "status_code": "pending",
  "amount": 1000,
  "currency": "UAH",
  "payout_type": "card",
  "created_at": "2024-01-15T10:30:00Z"
}

Перевірка статусу виплати

curl -X POST https://api.rozetkapay.com/api/payouts/v1/info \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "payout_12345"
  }'

Перевірка балансу

Перед виплатою перевірте доступний баланс:

curl -X GET https://api.rozetkapay.com/api/payouts/v1/account-balance \
  -u "login:password" \
  -H "Content-Type: application/json"

Відповідь

{
  "available_balance": 50000,
  "committed_balance": 10000,
  "currency": "UAH"
}

Поле	Опис
`available_balance`	Доступно для виплат
`committed_balance`	Зарезервовано (в обробці)

Повторна відправка callback

curl -X POST https://api.rozetkapay.com/api/payouts/v1/resend-callback \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "payout_12345"
  }'

Скасування готівкової виплати

Тільки для payout_type: cash:

curl -X POST https://api.rozetkapay.com/api/payouts/v1/cancel-payout \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "payout_12345"
  }'

Виплата на токенізовану картку

Якщо у вас є токен картки з попередньої операції:

curl -X POST https://api.rozetkapay.com/api/payouts/v1/request-payout \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "external_id": "payout_67890",
      "original_amount": "500",
      "currency": "UAH",
      "description": "Повернення коштів"
    },
    "payer": {
      "entity_id": "your_entity_id"
    },
    "recipient": {
      "payout_type": "card",
      "card": {
        "first_name": "Іван",
        "last_name": "Петренко",
        "card_data": {
          "token": "tok_abc123"
        }
      }
    }
  }'

Статуси виплат

Статус	Опис
`init`	Виплата створена
`pending`	В обробці
`success`	Виплата успішна
`failure`	Виплата невдала

Callback виплати

При зміні статусу виплати на callback_url надсилається POST запит:

{
  "id": "payout_abc123",
  "external_id": "payout_12345",
  "status": "success",
  "status_code": "transaction_successful",
  "amount": 1000,
  "currency": "UAH",
  "payout_type": "card",
  "processed_at": "2024-01-15T10:31:00Z"
}

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

┌─────────────────┐
│   Перевірка     │
│    балансу      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│    Створення    │────▶│     Pending     │
│     виплати     │     │                 │
└─────────────────┘     └────────┬────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Success      │     │    Failure      │     │  (для cash)     │
│   Кошти на      │     │   Помилка       │     │    Cancel       │
│    картці       │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┴───────────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │    Callback     │
                        └─────────────────┘