Приймання й виплати через один узгоджений контракт

Огляд

Кожен запит підписується й іде на версійований шлях /api/v1/…. Версія живе у шляху: коли зʼявиться v2, ваша інтеграція на v1 продовжить працювати без змін. Усередині версії ми лише додаємо поля — ніколи не прибираємо й не перейменовуємо.

Автентифікація & підпис

До кожного запиту додайте два заголовки. Порядок перевірки на сервері: ліміт частоти → цілісність тіла → ключ → підпис, тож помилка називає саме свою причину.

Підписується точні байти тіла, які ви відправляєте — серіалізуйте JSON один раз і підпишіть саме цей рядок. У GET-запитів тіло порожнє, тож X-Signature — це HMAC порожнього рядка з api_secret.

# тіло, яке відправляємо
BODY='{"order_id":"A-1001","amount":1500.00,"currency":"UAH"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

curl -X POST https://yuppipay.net/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

Додатково: якщо у профілі задано білий список IP, запити приймаються лише з нього (перевіряється REMOTE_ADDR, X-Forwarded-For ігнорується).

Ідемпотентність

Заявки й виплати ідемпотентні за парою (мерчант, order_id). Точний повтор того самого запиту повертає оригінальний обʼєкт (не створює дубль). Той самий order_id зі зміненим тілом (сума, валюта, платник / картка отримувача) — це конфлікт 409 idempotency_conflict, у відповіді буде наявний обʼєкт.

Заявки на приймання

Створює заявку payin і повертає реквізит (картку), який показуєте платнику. Комісія утримується з суми (inclusive): мерчанту зараховується amount − commission.

{
  "order_id": "A-1001",
  "amount": 1500.00,
  "currency": "UAH",
  "payer_id": "user-42"
}

{
  "id": "7af7c1df-0629-42d4-9068-df6500b3acd6",
  "order_id": "A-1001",
  "status": "awaiting_payment",
  "amount": 1500.00,
  "amount_settled": null,
  "commission": 30.00,
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "payer_id": "user-42",
  "requisite": {
    "card_number": "5375 4141 0000 1234",
    "card_holder": "ПЕТРЕНКО ІВАН",
    "bank": "PrivatBank",
    "type": "card"
  },
  "created_at": "2026-08-09T10:00:00+00:00",
  "expires_at": "2026-08-09T10:15:00+00:00",
  "completed_at": null
}

Показуйте requisite.card_number платнику; чекайте на вебхук order.completed (не поллінг). Поле id — це {uuid} для запиту статусу.

Повертає поточний стан заявки (той самий обʼєкт, що й POST /orders). Заявка іншого мерчанта невидима навіть за відомим UUID.

Зняти заявку, яку ще не оплатили: платник передумав або оператор закриває її з вашого боку. Картка трейдера одразу звільняється під наступну заявку. У відповідь приходить той самий обʼєкт заявки зі статусом cancelled, і на ваш callback_url іде подія order.cancelled.

Тіло не обовʼязкове. Можна передати reason — причина потрапить у вебхук, у журнал і в картку заявки, де її бачить оператор платіжної системи, тож пишіть зрозумілий текст, а не службовий код; порожнє тіло {} теж приймається, тоді запишеться «Cancelled by merchant». Підписуйте рівно той рядок, який надсилаєте.

Скасувати можна лише неоплачену заявку — статуси pending і awaiting_payment. Щойно платник переказав гроші (processing) або відкрито спір, скасування через API вже не працює: кошти могли надійти на картку трейдера, і такий випадок закриває підтримка. Відповідь — 409 order_not_cancellable і поточний стан заявки в полі order.

Виплати

Створює виплату на картку отримувача. Комісія додається зверху (on-top): з мерчанта списується amount + commission = amount_charged.

{
  "id": "b1e2c3d4-5678-90ab-cdef-1234567890ab",
  "order_id": "P-2001",
  "status": "pending",
  "amount": 1000.00,
  "commission": 15.00,
  "amount_charged": 1015.00,
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "recipient": { "card_number": "4149 •••• •••• 3179", "name": "IVAN P.", "bank": "A-Bank" },
  "receipt_attached": false,
  "created_at": "2026-08-09T10:00:00+00:00",
  "expires_at": "2026-08-09T14:00:00+00:00",
  "completed_at": null
}

Стан виплати (той самий обʼєкт, що й при створенні), scoped до вашого мерчанта.

Відкликати виплату, поки її ніхто не взяв. Тіло порожнє — надішліть {} і підпишіть саме ці два байти. У відповідь приходить той самий обʼєкт виплати зі статусом cancelled, і на ваш callback_url іде подія payout.cancelled.

Щойно виплату взяв трейдер, скасувати її через API вже не можна: він міг почати переказ. Такий випадок закриває підтримка — відповідь 409 payout_not_cancellable і поточний стан виплати в полі payout.

Баланс

Баланс і оборот у розрізі валют, рахуються так само, як у кабінеті: зараховано − видано − холд під незавершені виплати − заявки на вивід + правки (заявки — у резервуючих статусах; правки — ручні корекції адміністратора, поле adjustments).

{
  "merchant_id": 1,
  "balances": [
    {
      "currency": "UAH",
      "balance": 598229.84,
      "settled": 6449109.84,
      "paid_out": 5849865.00,
      "held": 1015.00,
      "withdrawn": 0.00,
      "adjustments": 0.00,
      "turnover": 7010100.00,
      "commission": 560792.16,
      "orders": 438,
      "payouts": 56,
      "withdrawals": 0
    }
  ],
  "generated_at": "2026-08-09T10:15:00+00:00"
}

Вебхуки

Ми надсилаємо POST на вашу адресу доставки на ключові переходи — завершення й прострочення заявки, корекцію суми, і зміни виплат — а не буквально на кожну зміну статусу. Відповідайте 2xx швидко; тіло обробляйте ідемпотентно.

Події заявок

Канонічний payload однаковий для всіх подій order.*: незмінний порядок і назви полів.

Ручний повтор із адмінки надсилає той самий payload із додатковим прапорцем "resent": true.

{
  "event": "order.completed",
  "order_id": "7af7c1df-0629-42d4-9068-df6500b3acd6", // наш uuid
  "merchant_order_id": "A-1001",                      // ваш номер
  "status": "completed",
  "currency": "UAH",
  "amount": 1500.00,                                  // заявлена (не змінюється)
  "amount_received": 1500.00,                         // фактично отримана
  "amount_settled": 1470.00,                          // до зарахування (мінус комісія)
  "exchange_rate": 45.58,
  "settlement_currency": "USDT"
}

{
  "event": "order.amount_corrected",
  "order_id": "7af7c1df-0629-42d4-9068-df6500b3acd6",
  "merchant_order_id": "A-1001",
  "status": "completed",
  "currency": "UAH",
  "amount": 1500.00,
  "amount_received": 1400.00,
  "amount_settled": 1372.00,
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "correction_id": 42,
  "reason": "partial_payment",
  "amount_original": 1500.00, // сума до корекції
  "amount_corrected": 1400.00 // нова сума
}

Події виплат

{
  "event": "payout.completed",
  "payout_id": "b1e2c3d4-5678-90ab-cdef-1234567890ab", // наш uuid
  "order_id": "P-2001",                                // ВАШ зовнішній номер
  "amount": 1000.00,
  "amount_charged": 1015.00,                           // списано з мерчанта
  "currency": "UAH",
  "exchange_rate": 45.58,
  "settlement_currency": "USDT",
  "status": "completed",
  "tx_receipt": "https://.../receipt.jpg",
  "completed_at": "2026-08-09T10:15:00+00:00"
}

Доставка & ретраї

Доставка асинхронна через чергу. Успіх — будь-який 2xx. Не-2xx або таймаут (connect 5с / read 15с) плануює повтор із наростаючою затримкою.

До 5 спроб; після вичерпання колбек позначається failed. Обробляйте ідемпотентно за order_id/payout_id — той самий колбек може прийти повторно.

Коди помилок

Усі помилки — JSON із полем error (машинний код) і message. Робіть switch по error, не по тексту.