Приём и выплаты через один согласованный контракт

Обзор

Каждый запрос подписывается и идёт на версионированный путь /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, не по тексту.