Вьетнам: VietQR, NAPAS 247 и MoMo находятся на разных уровнях платежа

Представим кассу с двумя кнопками: «VietQR» и «MoMo». В первом случае покупатель сканирует банковские реквизиты и переводит деньги. Во втором открывает согласованный платёжный сценарий MoMo. Обе оплаты могут выглядеть одинаково быстро, но оставляют разные идентификаторы и требуют разных подтверждений. Объединить их в один внутренний реестр можно; объявить одинаковыми их внешние статусы нельзя.

Особенно важно не считать VietQR и NAPAS 247 двумя последовательными независимыми платежами. В конкретном продукте NAPAS FastFund 247 через VietQR код служит удобным способом адресовать тот же банковский перевод. Ниже эта схема отделена от торгового API MoMo. Речь идёт о законном приёме выручки, а не о разрешении любой отрасли использовать местные рельсы.

Одна покупка через VietQR: что следует проверить

NAPAS описывает перевод между счетами банков-участников через сканирование VietQR, круглосуточно, с суммой одной операции менее 500 млн VND. Это описание данного transfer-продукта, а не любого QR-платежа во Вьетнаме. Код упрощает ввод банковских реквизитов, но не доказывает, что получатель является согласованным мерчантом вашего PSP. Описание NAPAS.

На стороне кассы полезно зафиксировать банк, счёт назначения, отображаемого получателя, ожидаемую сумму, платёжное назначение, время выдачи инструкции и срок действия заказа. Это рекомендуемые поля внутренней записи, не утверждение, что любой статический VietQR обязательно содержит их все. Если сумма или reference вводятся плательщиком, нужно заранее определить поведение при ошибке, отсутствии текста и оплате после закрытия заказа.

Опасная иллюзия выглядит так: «QR содержит номер заказа, значит банк вернёт номер заказа в удобном поле». Проверять необходимо весь путь: формирование инструкции, экран банка покупателя, фактический входящий перевод и экспорт получателя. Если текст обрезается, нормализуется или не передаётся вашим обслуживающим каналом, это обнаруживают на пилоте. Не создавайте автоматическое зачисление на основе свойства, которого договор и тест не подтвердили.

Для MoMo нужен торговый контур

Официальный onboarding MoMo последовательно предусматривает merchant profile, тестовую интеграцию, проверку аккаунта, production credentials, проверку на production и одобрение запуска. Это не описание прав личного кошелька. Доступ к тестовой среде доказывает возможность писать интеграцию, но не принятие отрасли, юридического лица или конкретного способа расчётов.

Разделите две проверки: документы предприятия и способность покупателя авторизовать платёж. Например, в актуальном перечне кодов MoMo есть отказ 4002, связанный с непроверенными через C06 данными и необходимостью обновления биометрии через NFC. Код 1004 относится к превышению дневного или месячного лимита, 1005 — к истёкшему URL либо QR. Это разные причины, и повторять запрос вслепую не является исправлением.

Пять идентификаторов вместо одного расплывчатого «ID»

В модели MoMo стоит различать partnerCode, orderId, requestId, transId и собственный ID заказа. Партнёр и заказ определяют контекст, requestId относится к запросу, transId выдаёт MoMo. При запросе статуса используются partnerCode, orderId, requestId и подпись. Названия и роли берутся из конкретной версии документации; значения сохраняются без потери регистра и форматирования.

Для собственного учёта добавьте номер попытки. Один заказ может пережить неоплаченную первую попытку и успешную вторую. Возврат будет связан с успешной финансовой операцией, а не просто с последней открытой страницей. Для каждой попытки храните ожидаемую сумму VND и полученный результат; название товара или номер телефона не используйте как ключ уникальности.

IPN важнее возвращения покупателя в браузер

MoMo отправляет результат на ipnUrl серверным POST. Документация требует проверки подписи и сопоставления partnerCode, orderId и amount; ответ получателя — HTTP 204 в пределах 15 секунд. resultCode 0 означает успех соответствующей операции, 9000 — успешную авторизацию. Последняя не должна автоматически считаться завершённым списанием в сценарии с отдельным capture. Правила IPN.

Собственная обработка должна быть идемпотентной: одно подтверждённое денежное событие создаёт одну запись, даже если уведомление пришло повторно. Рекомендуемый порядок — проверить запрос, надёжно записать событие, быстро подтвердить получение, а тяжёлую выдачу выполнить из очереди. Если уведомление потерялось, используйте официальный запрос статуса, не заставляя покупателя оплачивать заново ради появления новой квитанции.

Есть ещё одна граница: HTTP 2xx показывает успешную обработку API-запроса, но не заменяет проверку бизнес-кода и вида операции. Создание страницы оплаты, авторизация и окончательная успешная оплата отвечают на разные вопросы. В пользовательском сообщении следует говорить именно о подтверждённом состоянии, а не показывать «оплачено» при любом технически успешном ответе сервера.

Возврат — отдельная операция с собственным результатом

Refund API MoMo требует новый orderId возврата, отличный от исходного заказа, requestId, сумму и transId первоначальной успешной оплаты. Есть отдельный запрос результата refund. Частичный возврат не должен превысить оставшийся доступный к возврату остаток. Числовые ограничения документация различает по способу оплаты; один предел нельзя переносить на все продукты MoMo.

В учебном случае покупатель оплатил 400 000 VND, затем ему согласовали частичный возврат. Система резервирует утверждённую сумму возврата, связывает её с исходным transId и отслеживает результат отдельно. Если запрос завершился тайм-аутом, сначала выясняют, принят ли он. Создание нового refund с новым идентификатором без этой проверки рискует повторить возмещение.

Что остаётся за пределами платёжного API

Расчётный график, комиссии, резерв, разрешённые товары и право предприятия принимать деньги задаются договором и применимыми правилами. Проверка MoMo и наличие банковского счёта не заменяют отраслевое разрешение. Во Вьетнаме официальные органы отдельно разъясняют ответственность за организацию незаконных азартных игр; правила онлайн-игр также не приравнивают виртуальные предметы к свободно выводимым деньгам.

Поэтому пригодность местного метода для конкретного игрового бизнеса нельзя выводить из того, что QR сканируется или API отвечает. Практический результат хорошей интеграции другой: каждый законный платёж имеет доказанный статус, связанный заказ, понятное обязательство по расчёту и проверяемый возврат. VietQR, NAPAS 247 и MoMo занимают в этой картине разные роли, не требуя выдумывать три независимых движения денег.