После настройки проекта Proccesing, вы можете начинать обрабатывать платежи. В этом материале мы расскажем о процессе выставлении и обработки счетов, а также некоторые нюансы в работе
1
Выставление платежного поручения (Invoice)
2
Отправка реквизитов для оплаты
Шаг №1. Создание Invoice#
Получение валюты инвойса#
Перед началом работы с инвойсами, необходимо понять, в каких валютах вы можете выставить платежное поручение.При помощи данного метода вы получаете список доступных валют. Речь идет не о валюте оплаты, а о валюте платежного поручения.В вашем интернет-магазине покупатель выбрал товар с ценой в USD
Вам необходимо выставить счет в долларах, далее пользователь оплатит счет в нужном ему активе, сконвертированном к валюте счета (инвойса)
Создание Invoice#
С помощью данного метода вы можете создать Invoice, указав сумму и валюту поручения, срок его оплаты, а также доступные токены для оплатыШаг №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. Все идеи внимательно проанализируем и оперативно внесем изменения :) 