После настройки проекта Proccesing, вы можете начинать обрабатывать платежи. В этом материале мы расскажем о процессе выставлении и обработки счетов, а также некоторые нюансы в работе
1
Выставление платежного поручения (Invoice)
2
Отправка реквизитов для оплаты
Шаг №1. Создание Invoice#
Получение валюты инвойса#
Перед началом работы с инвойсами, необходимо понять, в каких валютах вы можете выставить платежное поручение.При помощи данного метода вы получаете список доступных валют. Речь идет не о валюте оплаты, а о валюте платежного поручения.В вашем интернет-магазине покупатель выбрал товар с ценой в USD
Вам необходимо выставить счет в долларах, далее пользователь оплатит счет в нужном ему активе, сконвертированном к валюте счета (инвойса)
Создание Invoice#
С помощью данного метода вы можете создать Invoice, указав сумму и валюту поручения, срок его оплаты, а также доступные токены для оплатыСсылка на платежную страницу#
После успешного создания инвойса в ответе возвращается его идентификатор orderId. Ссылка на платежную страницу формируется путём добавления полученного orderId к базовому URL: https://pay.rapira.net/invoices/{orderId}Идентификатор orderId также используется в последующих запросах для работы с созданным инвойсом.Шаг №2. Получение реквизитов для оплаты инвойса#
Получение доступных способов оплаты#
Метод возвращает доступные токены оплаты для конкретного инвойса, сгруппированные по сетям.понять, какие способы оплаты доступны именно для этого инвойса;
показать пользователю список доступн ых сетей и токенов для оплаты;
понять, сколько времени дается на каждый способ оплаты.
Если при создании инвойса вы ограничили его одним токеном, для пользователя возможен один вариант оплаты.не нужно показывать пользователю список токенов при помощи метода;
можно сразу переходить к получению адреса оплаты для единственного токена при помощи метода ниже ⬇️
Получение адреса для оплаты#
Возвращает платёжный адрес и параметры оплаты для указанного инвойса и выбранного платёжного токена:адрес выдаётся для конкретного инвойса и конкретного токена;
один адрес может переиспользоваться системой позже, но не может одновременно участвовать в нескольких активных инвойсах;
для активного инвойса адрес безопасно связан именно с ним;
каждый способ оплаты имеет своё время жизни, по его истечению в этом инвойсе нельзя будет воспользоваться этим способом оплаты.
Шаг №3. Обработка платежа#
Получение инвойса#
Возвращает информацию об инвойсе по его идентификатору. Позволяет получить текущий статус инвойса, доступные варианты оплаты, а также связанные депозиты.Получить историю инвойсовВозвращает список инвойсов в виде массива с поддержкой пагинации и фильтрации. Позволяет фильтровать результаты по проектам, сумме, валюте, статусу, транзакциям и времени создания.Возврат проблемных депозитов#
Rapira не работает с транзакциями сомнительного происхождения, не прошедших проверку AML!Если по инвойсу обнаружен проблемный депозит и инвойс получил статус REJECT, нужно указать адрес возврата.
2.
Посмотреть связанные депозиты;
3.
Запросить у покупателя адрес для проведения возврата;
4.
Взять нужный депозит и указать адрес возврата в методе.
Пояснение к полям инвойса и статусов#
Что такое amounts и selectedAmount#
Это список подготовленных вариантов оплаты по инвойсу.Это не просто “последний выбранный вариант”.Это тот вариант оплаты, в котором фактически была произведена оплата.инвойс выставлен на 1000 USD;
пользователь выбрал TRX_USDT;
тогда selectedAmount будет указывать именно на TRX_USDT.
Таймаут оплаты#
Поле timeToPayMinutes — это время жизни инвойса, задаваемое магазином.В рамках этого времени пользователь может выбирать и оплачивать доступные способы оплаты.Разные способы оплаты могут иметь разное время доступности.способ оплаты может стать недоступным раньше, чем закончится время инвойса;
после этого пользователь может выбрать другой
инвойс живёт в течение timeToPayMinutes;
каждый способ оплаты доступен ограниченное время (зависит от сети), см показатель expireTimestamp;
если время способа оплаты истекло:он больше не отображается;
выбрать его повторно нельзя;
при этом сам инвойс может оставаться активным.
Описание статусов инвойсов#
Ниже представлена статусная модель инвойсов и других его сущностей. Разберем подробнее
1
Статусы инвойса (invoice.status)
Это статус самого платежного поручения (документа)
2
Статусы оплаты (paymentStatus)
Это статус оплаты платежного поручения
3
Статусы депозита (depositStatus)
Статус депозита (транзации оплаты)
Статусы инвойса (invoice.status)#
UNPAID — оплаты ещё не было;PENDING_DEPOSIT — депозит получен, но ещё не завершён;SUCCESS — инвойс успешно завершён;CANCEL — инвойс завершён по таймауту;REJECT — по инвойсу обнаружен грязный депозит, требуетс я указать адрес возврата;RETURNED — средства возвращены пользователю, появляется после статуса REJECTПояснения по статусам инвойса:✅ Финальный успешный статус — только SUCCESS.Не нужно считать успешной оплату только потому, что:депозит (deposit.status) получил статус SUCCESS;
сумма была оплачена точно;
пришёл webhook без повторной проверки API.
Итоговый успех определяется только invoice.status = SUCCESS.
🔄 Промежуточное состояниеUNPAID - депозит не был отправленPENDING_DEPOSIT - депозит был отправлен, но находится в обработке блокчейном или отправлена не полная сумма⚠️ Промежуточное проблемное состояниеREJECT - появляется в случае нахождения проблем при AML-проверке. При получении этого статуса, нужно указать адрес возврата средств (см. метод ниже)❗ Финальные неуспешные состоянияCANCEL* - появляется, если платежное поручение не было оплачено в установленный срок;RETURNED - появляется после возврата грязного депозита (то есть после статуса REJECT) Late deposit (поздний депозит)*#
Для сетей с уникальными адресами (UNIQUE) поддерживается обработка поздних депозитов:Если депозит поступает после завершения инвойса (status = CANCEL), применяется следующая логика:если депозит однозначно соответствует ранее выданному адресу и платёжному контексту (CryptoPaymentQuote),то инвойс может быть переведён из CANCEL в:SUCCESS — при успешной проверке;
REJECT — при негативном результате проверки (например, AML).
применяется только для стратегий без переиспользования адресов (UNIQUE);
допускается только при отсутствии конкурирующих платёжных контекстов для этого адреса;
для сетей с переиспользованием адресов (ONLY_USER, FULL_SHARING) автоматический late matching не выполняется.
компенсировать задержки сети (например, долгий выход блока);
не терять корректные платежи пользователя
Статусы оплаты (paymentStatus)#
Пояснения по статусам оплаты:OVERPAID — переплата, излишки суммы уходят проектув таком случае, инвойс получает invoice.status = SUCCESS🔄 Промежуточное состояние:UNDERPAID - пользователь оплатил не полную сумму, но может оплатить остатокЕсли после доплаты общая сумма стала достаточной, инвойс может перейти в SUCCESS , если не успеет оплатить, то invoice.status = CANCELNONE — оплаты не было, но ожидается поступление. invoice.status = CANCEL появляется в случае отсутствия оплаты в срок
selectedAmount.Статусы депозита (depositStatus)#
MEMPOOL — транзакция замечена в мемпуле;PENDING_CONFIRMATION — ожидаются подтверждения сети;PENDING_AML — ожидается AML-проверка;MANUAL — депозит отправлен на ручную проверку;SUCCESS — депозит успешно зачислен;REJECT — депозит признан проблемным и подлежит возврату;RETURNED — проблемный депозит возвращён;CANCEL — технически существует, но практически не используется.Если депозит получает depositStatus = REJECT после AML-проверки, то invoice.status = REJECTПосле проведение возврата средств (см. метод ниже), depositStatus = RETURNED статус инвойса становится invoice.status = RETURNED
В этом материале мы подробно рассказали, как использовать API Rapira в проекте Crypto Processing.Если у вас есть пожелания по улучшению документации - ждем сообщений в поддержке на сайт или Telegram. Все идеи внимательно проанализируем и оперативно внесем изменения :) 