Приём платежа

Как создать платёж, куда отправить плательщика и как узнать исход.

Платёж создаёт сервер мерчанта одним запросом. Ответ на создание уже называет платёж: его номер, статус и куда отправить плательщика. Исход платежа узнаётся чтением.

Порядок

  1. Выберите сервис из списка сервисов. Сервис называет валюту, способ оплаты и поля плательщика: второй раз их не присылают.
  2. Создайте платёж с ключом повтора в заголовке Idempotency-Key:

    curl -sS -X POST https://api.paydex.co.uk/api/v1/payments \
      -H "Authorization: Bearer $PAYDEX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 5f0c2b9e-8d41-4a7c-9e2f-3b6d1a4c8e07" \
      -d '{
        "reference": "order-1001",
        "service": "pix_brl_redirect",
        "amountMinor": "1250",
        "customer": {
          "id": "player-42",
          "country": "BR"
        },
        "fields": {
          "payer.tax_id": "12345678909",
          "payer.name": "Maria Silva"
        },
        "returnUrl": "https://shop.example/return/order-1001",
        "metadata": {
          "cartId": "c-77"
        }
      }'

    Ответ 201 несёт платёж. Поля запроса и ответа: справочник.

  3. Отправьте плательщика по action: Что показать плательщику.
  4. Читайте платёж, пока исход не станет известен: Как узнать исход.
  5. Зачисляйте только при SUCCEEDED, когда inReview равен false, и ровно paidMinor: Статусы платежа.

Номер заказа reference уникален у мерчанта в контуре: второй платёж по тому же заказу не создаётся. Как повторить запрос, ответ на который не дошёл: Повтор запроса.

Что показать плательщику

Плательщика отправляют на страницу оплаты по pageUrl или показывают ему action своей формой:

  • redirect: отправьте плательщика по адресу action.url. Адрес returnUrl, если он задан, уходит провайдеру: туда плательщик вернётся после оплаты.
  • requisite: покажите реквизит, Реквизит.

action есть, только пока платёж ждёт плательщика: не в разборе и до срока expiresAt. null значит «ждать»: платёж ещё создаётся или проводится, стоит в разборе, реквизит ещё не выписан или срок вышел. Об отказе говорит статус, а не пустое action.

Реквизит

  • presentation говорит, как показать: qr код для сканирования и копирования, transfer реквизиты перевода, voucher номер для оплаты в кассе.
  • payload главная строка реквизита, fields подписи для экрана в порядке показа.
  • Показывайте сумму payAmountMinor в валюте payCurrency, а не сумму платежа: при конвертации они различаются. При payAmountChanged: true пишите плательщику «переведите ровно эту сумму»: провайдер узнаёт перевод по сумме.
  • Реквизит действует до action.expiresAt.

Срок оплаты

У каждого платежа есть срок expiresAt, его длину для мерчанта задаёт администратор Paydex. Не оплаченный к сроку платёж получает статус EXPIRED. Если провайдер подтвердит деньги позже, платёж всё равно перейдёт в SUCCEEDED, а при расхождении суммы в PARTIALLY_PAID или OVERPAID: Поздние деньги.

Как узнать исход

Исход приходит уведомлением payment.updated или узнаётся чтением платежа по номеру id из ответа на создание. Незавершённый платёж касса дочитывает сама, даже если ждёт уведомлений:

curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $PAYDEX_API_KEY"
  • Читайте каждый незавершённый платёж не чаще раза в 5 секунд. У чтения свой предел частоты, он общий на все ваши платежи и не тратит предел создания: Ограничения.
  • Остановитесь, когда статус финальный и inReview равен false, либо статус PARTIALLY_PAID или OVERPAID: их разбор через API не снимается, о деньгах решает наша сторона. EXPIRED единственный финальный статус, который ещё может смениться: о поздних деньгах скажет уведомление, но доставка не гарантирована, поэтому истёкшие платежи перечитывайте сверкой, например раз в сутки, с уведомлениями или без.
  • Исход платежа в разборе (inReview: true) решается на нашей стороне, доспросом провайдера или человеком. Читайте его раз в несколько минут.

Боевой контур

Боевым ключом платёж не создаётся: отказ 403 с правилом live_intake_closed, он описан в разделе Контуры. Тестовый контур работает полностью, исход в нём задают тестовые данные.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.