Приём платежа
Как создать платёж, куда отправить плательщика и как узнать исход.
Платёж создаёт сервер мерчанта одним запросом. Ответ на создание уже называет платёж: его номер, статус и куда отправить плательщика. Исход платежа узнаётся чтением.
Порядок
- Выберите сервис из списка сервисов. Сервис называет валюту, способ оплаты и поля плательщика: второй раз их не присылают.
Создайте платёж с ключом повтора в заголовке
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 несёт платёж. Поля запроса и ответа: справочник.
- Отправьте плательщика по
action: Что показать плательщику. - Читайте платёж, пока исход не станет известен: Как узнать исход.
- Зачисляйте только при
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, он описан в разделе Контуры. Тестовый контур работает полностью, исход в нём задают тестовые данные.