Банковский перевод (Вьетнам)

В панели администратора: Finance › Payment channels › VN bank transfer (/payments/bank). Курс обмена: Finance › Payment channels › Exchange rates (/payments/fx).

Назначение

Позволяет клиентам пополнять баланс в USD обычным банковским переводом во вьетнамских донгах. NexCMP показывает код VietQR, реквизиты счета и уникальный transfer memo; Sepay отслеживает поступления на ваш банковский счет и вызывает вебхук при получении средств, а NexCMP зачисляет их на баланс. Используйте этот способ, если вы работаете с клиентами во Вьетнаме.

Отображается только во вьетнамском интерфейсе

Оплата через банк Вьетнама предлагается клиенту только тогда, когда в портале выбран Vietnamese. Клиенты с любым другим языком интерфейса ее не увидят.

Требования

Параметр	Требование
Банковский счет	Вьетнамский банковский счет (или виртуальный счет Sepay, VA), подключенный к аккаунту Sepay на my.sepay.vn.
Sepay	Аккаунт Sepay с включенной интеграцией webhook.
Курс обмена валют	Должен быть задан курс USD к VND: сначала обновите его в Exchange rates. Без курса канал возвращает fx_unavailable, и клиенты не смогут начать перевод.
Сеть	Ваша панель должна быть доступна по HTTPS, чтобы Sepay мог вызывать https://<your-domain>/v1/billing/sepay/webhook.
Зависимости	Валюта и обменные курсы.

Подготовка инфраструктуры

На стороне Sepay:

1. В my.sepay.vn подключите банковский счет (или создайте VA) и убедитесь, что транзакции отображаются.
2. Определите префикс назначения платежа — от 2 до 5 заглавных букв, например PAY. NexCMP формирует назначение платежа как префикс, за которым следуют 8 случайных цифр (например, PAY48210937). Префикс не должен содержать ORD, и его не должна использовать ни одна другая система, принимающая средства на этот же счет.
3. Если в вашем аккаунте Sepay используется payment code structure, зарегистрируйте там тот же префикс, чтобы Sepay распознавал назначение платежа.
4. Создайте webhook позже, когда на странице NexCMP появятся URL и ключ (шаг 7 ниже).

Подключение в NexCMP

1. Откройте Finance › Payment channels › Exchange rates и нажмите Update exchange rates, если курс еще не сохранен.

2. Откройте Finance › Payment channels › VN bank transfer (/payments/bank).

3. В разделе Receiving account заполните:

   Поле	Пример	Правило
   Банк	VCB Vietcombank	Выберите из списка; BIN заполнится автоматически.
   Номер счета	0123456789	4–24 цифры или заглавные буквы.
   Виртуальный счет (VA — необязательно)		Если указано, клиенты переводят средства на VA, и он отображается в QR-коде.
   Имя владельца счета	NGUYEN VAN A	Без диакритики, ВЕРХНИЙ РЕГИСТР, 2–60 символов.
   Префикс назначения платежа	PAY	2–5 заглавных букв, без ORD.

4. В разделе Webhook authentication выберите Auth method: HMAC-SHA256 (рекомендуется) или API key, и введите Webhook key / HMAC secret (8–200 символов). При необходимости укажите userapi token от Sepay; он используется только для сверки переводов, webhook по которым был утерян.

5. В разделе Channel & limits задайте лимиты (значения по умолчанию указаны в скобках): Min / order (10,000 VND), Max / order (200,000,000 VND), Order expiry (120 минут, 15–1440), Max pending orders / account (3, 1–10), Reconcile every (10 минут) и, при необходимости, Allowed webhook IPs (через запятую; если поле не заполнено, IP-адрес только записывается в журнал).

6. Нажмите Save. Красный баннер «Sepay not configured» исчезнет, как только счет, имя, префикс и ключ станут корректными.

7. Скопируйте Webhook URL to paste into my.sepay.vn (он имеет вид https://<your-domain>/v1/billing/sepay/webhook) с помощью Copy. В Sepay откройте интеграцию вебхука, вставьте URL, выберите тот же тип аутентификации и ключ и включите событие «money in».

8. Нажмите Test connection. Затем включите Enable Sepay for clients (main site) и нажмите Save.

Безопасность webhook

Метод	Что должен отправлять Sepay
HMAC-SHA256	Заголовок X-SePay-Signature: sha256=<hex>, вычисленный для "<X-SePay-Timestamp>.<raw body>"; разница во времени не должна превышать 300 секунд.
API-ключ	Заголовок Authorization: Apikey <key>.

Проверяются только заголовки (тело запроса и строка параметров никогда не проверяются), при этом сравнение выполняется за константное время. Обрабатываются только входящие переводы (transferType = in) на настроенный счет или виртуальный счет (VA). Каждая транзакция Sepay сохраняется один раз, поэтому повторный вызов вебхука никогда не приводит к двойному зачислению. NexCMP возвращает 200 {"success":true} даже при намеренном игнорировании транзакции, а статус HTTP 5xx — только при временных сбоях, чтобы Sepay повторил попытку.

Как клиент производит оплату

1. В разделе Billing › Deposit (вьетнамский интерфейс) клиент выбирает вариант банковского перевода по Вьетнаму, указывает сумму и нажимает кнопку создания перевода.
2. NexCMP конвертирует сумму в USD по сохраненному курсу (с учетом маржи и шага округления, заданных в Exchange rates) и округляет сумму в VND в большую сторону до шага округления.
3. Клиент видит QR-код (VietQR, генерируется локально) с номером счета, банком, суммой и назначением платежа.
4. После перевода Sepay вызывает вебхук, и NexCMP начисляет floor(VND received × 100 / rate) центов. Курс фиксируется при создании заказа; если средства поступают после истечения срока действия заказа, применяется более высокий курс из зафиксированного и текущего.
5. Срок действия заказов истекает через Order expiry; для подстраховки каждые Reconcile every минут выполняется сверка (требуется токен userapi).

Проверка

1. Создайте тестовый заказ от имени клиента во вьетнамском интерфейсе. Убедитесь, что сумма, счет и назначение платежа указаны верно.
2. Переведите минимально допустимую сумму, точно указав назначение платежа.
3. В течение минуты в портале отобразится завершение пополнения, а баланс кошелька увеличится; на карточке State страницы банка появится время последнего вебхука.
4. Откройте Finance › Billing › Top-ups и убедитесь, что платеж отображается с полученной суммой в VND.

Ограничения и примечания

• Минимум. Минимальная сумма в VND, которую видит клиент, представляет собой большее из значений Min / order и эквивалента minimum top-up в VND.
• Незавершенные заказы. У клиента может быть не более Max pending orders / account открытых заказов (по умолчанию 3).
• Повтор назначения платежа. Повторный перевод с тем же назначением создает второй завершенный платеж по текущему курсу.
• Автоматический возврат на банковский счет не предусмотрен.
• Комиссия. Для этого канала нет отдельной фиксированной комиссии в Fees & limits; единственной корректировкой является маржа курса.
• Resellers могут настроить собственный аккаунт; URL их вебхука заканчивается на /v1/billing/sepay/webhook/r/<id>.

Несопоставленные переводы

Средства, поступившие на счет, но не содержащие корректного назначения платежа, отображаются в блоке Unmatched transactions внизу страницы (фильтр All channel owners или Master). Уточните у клиента банковский идентификатор платежа, затем нажмите Assign и выберите аккаунт. Баланс кошелька пополнится по текущему курсу.

Устранение неполадок

Симптом	Причина	Решение
Баннер «Sepay not configured»	Банк, счет, имя владельца, префикс или ключ отсутствуют либо указаны неверно	Заполните карточки Receiving account и Webhook authentication.
Баннер «USD/VND rate blocked» (fx_unavailable)	Курс обмена не сохранен	Exchange rates › Update exchange rates.
prefix: 2–5 capital letters, no ORD	Недопустимый префикс	Используйте от 2 до 5 заглавных букв без ORD.
Ошибка account_name	Диакритические знаки или строчные буквы	Используйте ЗАГЛАВНЫЕ буквы без диакритики, цифры, пробел, точку или дефис.
webhook_secret: 8–200 characters	Ключ слишком короткий	Используйте не менее 8 печатных символов.
Клиент не видит этот способ оплаты	Интерфейс не на вьетнамском языке, переключатель выключен или не задан курс	Проверьте язык, переключатель и курс.
Клиент оплатил, но средства не зачислены	Webhook не поступил, назначение платежа изменено или указана неверная сумма	Проверьте журнал webhook в SePay; если назначение платежа было неверным, перевод будет в Unmatched transactions.
Webhook возвращает ошибку 401 или 403	Несоответствие метода аутентификации или ключа	Используйте одинаковые метод и ключ в SePay и NexCMP.
Клиент видит ошибку «Too many pending requests»	Достигнут лимит заказов в обработке	Завершите их или дождитесь истечения срока действия.