Transferência bancária (Vietnã)

Onde no admin: Finance › Payment channels › VN bank transfer (/payments/bank). Taxa de câmbio: Finance › Payment channels › Exchange rates (/payments/fx).

O que faz

Permite que os clientes recarreguem a carteira em USD por meio de uma transferência bancária normal em dong vietnamita. O NexCMP exibe um código VietQR, os detalhes da conta e um transfer memo exclusivo; o Sepay monitora sua conta bancária e chama um webhook quando o dinheiro chega, e o NexCMP credita a carteira. Use-o se você vende para clientes no Vietnã.

Mostrado apenas na interface vietnamita

A opção de banco do Vietnã é oferecida ao cliente apenas quando o portal é exibido em Vietnamese. Clientes em qualquer outro idioma nunca a veem.

Requisitos

Item	Requisito
Conta bancária	Uma conta bancária vietnamita (ou uma conta virtual Sepay, VA) conectada a uma conta Sepay em my.sepay.vn.
Sepay	Uma conta Sepay com integração de webhook ativada.
Taxa de câmbio	É preciso que exista uma taxa de câmbio de USD para VND: atualize-a primeiro em Exchange rates. Sem uma taxa, o canal responde fx_unavailable e os clientes não conseguem iniciar uma transferência.
Rede	Seu painel deve estar acessível por HTTPS para que o Sepay possa chamar https://<your-domain>/v1/billing/sepay/webhook.
Dependências	Moeda e taxas de câmbio.

Preparar a infraestrutura

No lado do Sepay:

1. Em my.sepay.vn, conecte sua conta bancária (ou crie uma VA) e certifique-se de que as transações apareçam.
2. Defina o prefixo do memorando — 2 a 5 letras maiúsculas, por exemplo PAY. O NexCMP gera o memorando como o prefixo seguido por 8 dígitos aleatórios (por exemplo PAY48210937). O prefixo não deve conter ORD e não deve ser usado por nenhum outro sistema que receba dinheiro na mesma conta.
3. Se a sua conta Sepay usar uma estrutura de código de pagamento, registre o mesmo prefixo lá para que o Sepay reconheça o memorando.
4. Crie o webhook mais tarde, após a página do NexCMP fornecer a URL e a chave (etapa 7 abaixo).

Conectar no NexCMP

1. Abra Finance › Payment channels › Exchange rates e clique em Update exchange rates se nenhuma taxa tiver sido armazenada.

2. Abra Finance › Payment channels › VN bank transfer (/payments/bank).

3. Em Receiving account, preencha:

   Campo	Exemplo	Regra
   Banco	VCB Vietcombank	Escolha na lista; o BIN é preenchido automaticamente.
   Número da conta	0123456789	4–24 dígitos ou letras maiúsculas.
   Conta virtual (VA — opcional)		Se definida, os clientes transferem para a VA e o QR code a exibe.
   Nome do titular da conta	NGUYEN VAN A	Sem acentos, MAIÚSCULAS, 2–60 caracteres.
   Prefixo do memorando de transferência	PAY	2–5 letras maiúsculas, sem ORD.

4. Em Webhook authentication, escolha Auth method: HMAC-SHA256 (recomendado) ou API key e insira a Webhook key / HMAC secret (8–200 caracteres). Opcionalmente, insira o userapi token do Sepay; ele é usado apenas para reconciliar transferências cujo webhook foi perdido.

5. Em Channel & limits, defina os limites (padrões entre parênteses): Min / order (10,000 VND), Max / order (200,000,000 VND), Order expiry (120 minutos, 15–1440), Max pending orders / account (3, 1–10), Reconcile every (10 minutos) e, opcionalmente, Allowed webhook IPs (separados por vírgula; vazio significa que o IP é apenas registrado).

6. Clique em Save. O banner vermelho "Sepay not configured" desaparece assim que a conta, o nome, o prefixo e a chave forem válidos.

7. Copie a Webhook URL to paste into my.sepay.vn (ela exibe https://<your-domain>/v1/billing/sepay/webhook) com Copy. No Sepay, abra a integração de webhook, cole a URL, escolha o mesmo tipo e chave de autenticação e ative o evento "money in".

8. Clique em Test connection. Em seguida, ative Enable Sepay for clients (main site) e Save.

Segurança do webhook

Método	O que o Sepay deve enviar
HMAC-SHA256	Cabeçalho X-SePay-Signature: sha256=<hex>, calculado sobre "<X-SePay-Timestamp>.<raw body>"; o carimbo de data/hora pode diferir em no máximo 300 segundos.
Chave de API	Cabeçalho Authorization: Apikey <key>.

Apenas os cabeçalhos são verificados (nunca o corpo ou a query string) e a comparação é de tempo constante. Apenas transferências de entrada (transferType = in) para sua conta configurada ou VA são usadas. Cada transação do Sepay é armazenada uma única vez, portanto um webhook retentado nunca credita duas vezes. O NexCMP responde com 200 {"success":true} mesmo quando ignora deliberadamente uma transação, e HTTP 5xx apenas para erros temporários para que o Sepay retente.

Como o cliente paga

1. Em Billing › Deposit (interface em vietnamita), o cliente escolhe a opção de transferência bancária em VND e um valor, depois clica no botão de criar transferência.
2. O NexCMP converte o valor em USD na taxa armazenada (incluindo a margem e a etapa de arredondamento definidas em Exchange rates) e arredonda o valor em VND para cima até a etapa de arredondamento.
3. O cliente vê um QR code (VietQR, gerado localmente) com o número da conta, banco, valor e memorando.
4. Após a transferência, o Sepay chama o webhook e o NexCMP credita floor(VND received × 100 / rate) centavos. A taxa é fixada quando o pedido é criado; se o dinheiro chegar após o pedido expirar, usa-se a maior entre a taxa fixada e a atual.
5. Os pedidos expiram após Order expiry; a reconciliação é executada a cada Reconcile every minutos como rede de segurança (requer o token userapi).

Verificar

1. Crie um pedido de teste como cliente na interface em vietnamita. Verifique se o valor, a conta e o memorando estão corretos.
2. Transfira o menor valor permitido com o memorando exato.
3. Em até um minuto, o portal mostra o depósito como concluído e a carteira aumenta; o cartão State na página do banco mostra a hora do último webhook.
4. Abra Finance › Billing › Top-ups e verifique se o pagamento está listado com o valor em VND recebido.

Limites e notas

• Mínimo. O valor mínimo em VND que o cliente vê é o maior entre Min / order e o valor em VND do minimum top-up.
• Pedidos pendentes. Um cliente pode ter apenas Max pending orders / account pedidos em aberto (padrão 3).
• Mesmo memorando duas vezes. Transferir duas vezes com o mesmo memorando cria um segundo pagamento concluído à taxa atual.
• Sem reembolso automático para uma conta bancária.
• Taxa. O canal não possui uma linha de taxa fixa em Fees & limits; a margem da taxa é o único ajuste.
• Resellers podem configurar sua própria conta; a URL do webhook deles termina com /v1/billing/sepay/webhook/r/<id>.

Transferências não correspondidas

O dinheiro que chegou à conta, mas não traz um memorando válido, aparece em Unmatched transactions na parte inferior da página (filtre por All channel owners ou Master). Verifique a referência bancária com o cliente, clique em Assign e selecione a conta. A carteira é creditada à taxa atual.

Resolução de problemas

Sintoma	Causa	Correção
Banner "Sepay não configurado"	Banco, conta, nome do titular, prefixo ou chave ausentes ou inválidos	Preencha os cartões Receiving account e Webhook authentication.
Banner "Taxa USD/VND bloqueada" (fx_unavailable)	Nenhuma taxa de câmbio armazenada	Exchange rates › Update exchange rates.
prefix: 2–5 capital letters, no ORD	Prefixo inválido	Use de 2 a 5 letras maiúsculas sem ORD.
Erro account_name	Acentos ou letras minúsculas	Use letras MAIÚSCULAS sem acento, dígitos, espaço, ponto ou hífen.
webhook_secret: 8–200 characters	Chave muito curta	Use pelo menos 8 caracteres imprimíveis.
O cliente não consegue ver a opção	Não está na interface em vietnamita, desativado ou sem taxa	Verifique o idioma, o interruptor e a taxa.
Cliente pagou, mas nada foi creditado	O webhook não chegou, memorando alterado, valor incorreto	Verifique o log de webhook do Sepay; a transferência ficará em Unmatched transactions se o memorando estiver incorreto.
O webhook retorna 401 ou 403	Incompatibilidade no método de autenticação ou na chave	Use o mesmo método e chave no Sepay e no NexCMP.
O cliente vê "Too many pending requests"	Limite de pedidos pendentes atingido	Eles terminam ou aguardam a expiração.