Виплати — RozetkaPay Docs

Виплати (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 картки з гаманця

Відповідь

{
  "transaction_id": "b2f1c8d4-5a3e-4c7b-9d10-2e6f8a1b3c5d",
  "external_id": "payout_12345",
  "status": "pending",
  "status_code": "transaction_in_progress",
  "original_amount": "1000",
  "payer_amount": "1000",
  "currency": "UAH",
  "payout_type": "card"
}

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

external_id передається як query-параметр:

curl -X GET "https://api.rozetkapay.com/api/payouts/v1/info?external_id=payout_12345" \
  -u "login:password"

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

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

curl -X GET "https://api.rozetkapay.com/api/payouts/v1/account-balance?merchant_entity_id=entity_123" \
  -u "login:password"

Відповідь

{
  "available_amount": 30523.44,
  "commitment_amount": 199.99
}

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

Повторна відправка 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 виплати

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

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