---
title: Transferência bancária (Vietnã)
description: Aceite transferências bancárias (VND) com Sepay — conta de destino, prefixo de memo, webhook, limites e como atribuir transações não conciliadas.
url: https://nexcmp.com/pt/docs/billing/bank-transfer-vn/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Transferência bancária (Vietnã) {#bank-transfer-vietnam}

> **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 {#what-it-does}

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](https://sepay.vn) 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ã.

::: info 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 {#requirements}

| 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](https://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](https://nexcmp.com/pt/docs/catalog/currency-and-exchange-rates/). |

## Preparar a infraestrutura {#prepare-the-infrastructure}

No lado do Sepay:

1. Em [my.sepay.vn](https://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 {#connect-in-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**.

![Página de transferência bancária VN com a conta de recebimento, o prefixo do memorando e a autenticação de webhook preenchidos com valores de exemplo](https://nexcmp.com/pt/docs/images/billing/bank-transfer-vn-01-config.webp)

![Card de canal e limites com o botão do Sepay ativado e os limites padrão](https://nexcmp.com/pt/docs/images/billing/bank-transfer-vn-02-limits.webp)

### Segurança do webhook {#webhook-security}

| 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 {#how-the-customer-pays}

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 {#verify}

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 {#limits-notes}

- **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](https://nexcmp.com/pt/docs/billing/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 {#unmatched-transfers}

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 {#troubleshooting}

| 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. |