Bonifico bancario (Vietnam)

Dove trovarlo nell'amministrazione: Finance › Payment channels › VN bank transfer (/payments/bank). Tasso di cambio: Finance › Payment channels › Exchange rates (/payments/fx).

Descrizione

Permette ai clienti di ricaricare il portafoglio USD tramite un normale bonifico bancario in dong vietnamiti. NexCMP mostra un codice VietQR, i dettagli del conto e una causale di bonifico univoca; SePay monitora il tuo conto bancario e chiama un webhook quando i fondi arrivano, e NexCMP accredita il portafoglio. Usalo se vendi a clienti in Vietnam.

Mostrato solo nell'interfaccia vietnamita

L'opzione per le banche vietnamite viene proposta a un cliente solo quando il portale è visualizzato in Vietnamese. I clienti con qualsiasi altra lingua non la vedranno mai.

Requisiti

Elemento	Requisito
Conto bancario	Un conto bancario vietnamita (o un conto virtuale Sepay, VA) collegato a un account Sepay su my.sepay.vn.
Sepay	Un account Sepay con integrazione webhook abilitata.
Tasso di cambio	Deve esistere un tasso di cambio da USD a VND: aggiornalo prima in Exchange rates. Senza un tasso il canale risponde fx_unavailable e i clienti non possono avviare un trasferimento.
Rete	Il tuo pannello deve essere raggiungibile tramite HTTPS affinché Sepay possa chiamare https://<your-domain>/v1/billing/sepay/webhook.
Dipendenze	Valuta e tassi di cambio.

Prepara l'infrastruttura

Dal lato Sepay:

1. In my.sepay.vn collega il tuo conto bancario (o crea un VA) e assicurati che le transazioni compaiano.
2. Decidi il prefisso della causale — da 2 a 5 lettere maiuscole, ad esempio PAY. NexCMP genera la causale come il prefisso seguito da 8 cifre casuali (ad esempio PAY48210937). Il prefisso non deve contenere ORD e non dovrebbe essere utilizzato da nessun altro sistema che riceve denaro sullo stesso conto.
3. Se il tuo account Sepay utilizza una struttura del codice di pagamento, registra lo stesso prefisso lì in modo che Sepay riconosca la causale.
4. Crea il webhook in un secondo momento, dopo che la pagina di NexCMP ti avrà fornito l'URL e la chiave (passaggio 7 di seguito).

Collega in NexCMP

1. Apri Finance › Payment channels › Exchange rates e fai clic su Update exchange rates se non è stato memorizzato alcun tasso.

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

3. In Receiving account compila:

   Campo	Esempio	Regola
   Banca	VCB Vietcombank	Scegli dall'elenco; il BIN viene compilato automaticamente.
   Numero di conto	0123456789	4–24 cifre o lettere maiuscole.
   Conto virtuale (VA — facoltativo)		Se impostato, i clienti effettuano il bonifico sul VA e il QR lo mostra.
   Nome del titolare del conto	NGUYEN VAN A	Senza accenti, MAIUSCOLO, 2–60 caratteri.
   Prefisso causale bonifico	PAY	2–5 lettere maiuscole, senza ORD.

4. In Webhook authentication scegli Auth method: HMAC-SHA256 (consigliato) o API key, e inserisci la Webhook key / HMAC secret (8–200 caratteri). Facoltativamente, inserisci il userapi token di Sepay; viene utilizzato solo per riconciliare i bonifici il cui webhook è andato perso.

5. In Channel & limits imposta i limiti (valori predefiniti tra parentesi): Min / order (10,000 VND), Max / order (200,000,000 VND), Order expiry (120 minuti, 15–1440), Max pending orders / account (3, 1–10), Reconcile every (10 minuti) e, opzionalmente, Allowed webhook IPs (separati da virgola; se vuoto, l'IP viene solo registrato).

6. Fai clic su Save. Il banner rosso "Sepay not configured" scompare non appena l'account, il nome, il prefisso e la chiave sono validi.

7. Copia Webhook URL to paste into my.sepay.vn (riporta https://<your-domain>/v1/billing/sepay/webhook) con Copy. In SePay apri l'integrazione webhook, incolla l'URL, seleziona gli stessi tipo e chiave di autenticazione e abilita l'evento "money in".

8. Fai clic su Test connection. Quindi attiva Enable Sepay for clients (main site) e Save.

Sicurezza dei webhook

Metodo	Cosa deve inviare Sepay
HMAC-SHA256	Header X-SePay-Signature: sha256=<hex>, calcolato su "<X-SePay-Timestamp>.<raw body>"; la marca temporale può differire di al massimo 300 secondi.
Chiave API	Header Authorization: Apikey <key>.

Vengono controllati solo gli header (mai il corpo o la query string) e il confronto è a tempo costante. Vengono utilizzati solo i trasferimenti in entrata (transferType = in) verso il conto o VA configurato. Ogni transazione Sepay viene memorizzata una sola volta, quindi un webhook ritentato non accredita mai due volte. NexCMP risponde 200 {"success":true} anche quando ignora deliberatamente una transazione, e HTTP 5xx solo per errori temporanei in modo che Sepay riprovi.

Come paga il cliente

1. In Billing › Deposit (interfaccia in vietnamita) il cliente sceglie l'opzione di bonifico bancario VN e un importo, quindi fa clic sul pulsante per creare il bonifico.
2. NexCMP converte l'importo in USD al tasso memorizzato (inclusi il margine e la fase di arrotondamento impostati in Exchange rates) e arrotonda l'importo in VND per eccesso alla fase di arrotondamento.
3. Il cliente visualizza un codice QR (VietQR, generato localmente) con numero di conto, banca, importo e causale.
4. Dopo il bonifico, Sepay chiama il webhook, NexCMP accredita floor(VND received × 100 / rate) centesimi. Il tasso viene bloccato alla creazione dell'ordine; se il denaro arriva dopo la scadenza dell'ordine, viene utilizzato il maggiore tra il tasso bloccato e quello corrente.
5. Gli ordini scadono dopo Order expiry; la riconciliazione viene eseguita ogni Reconcile every minuti come rete di sicurezza (richiede il token userapi).

Verifica

1. Crea un ordine di test come cliente sull'interfaccia vietnamita. Verifica che l'importo, il conto e la causale siano corretti.
2. Effettua il bonifico dell'importo minimo consentito con la causale esatta.
3. Entro un minuto il portale mostra il deposito come completato e il credito aumenta; la scheda State nella pagina della banca mostra l'ora dell'ultimo webhook.
4. Apri Finance › Billing › Top-ups e verifica che il pagamento sia elencato con l'importo in VND ricevuto.

Limiti e note

• Minimo. Il minimo in VND visualizzato da un cliente è il maggiore tra Min / order e il valore in VND del minimum top-up.
• Ordini in sospeso. Un cliente può avere solo Max pending orders / account ordini aperti (predefinito 3).
• Stessa causale due volte. Effettuare due bonifici con la stessa causale crea un secondo pagamento completato al tasso corrente.
• Nessun rimborso automatico su un conto bancario.
• Commissione. Il canale non ha una riga di commissione fissa in Fees & limits; il margine sul tasso è l'unico adeguamento.
• I Resellers possono configurare il proprio conto; l'URL del loro webhook termina con /v1/billing/sepay/webhook/r/<id>.

Trasferimenti non abbinati

Il denaro arrivato sul conto ma privo di una causale valida compare in Unmatched transactions in fondo alla pagina (filtra per All channel owners o Master). Verifica il riferimento bancario con il cliente, quindi fai clic su Assign e seleziona il conto. Il portafoglio viene accreditato al tasso corrente.

Troubleshooting

Sintomo	Causa	Soluzione
Banner "SePay non configurato"	Banca, conto, nome titolare, prefisso o chiave mancanti o non validi	Completa le schede Receiving account e Webhook authentication.
Banner "Tasso USD/VND bloccato" (fx_unavailable)	Nessun tasso di cambio memorizzato	Exchange rates › Update exchange rates.
prefix: 2–5 capital letters, no ORD	Prefisso non valido	Usa 2–5 lettere maiuscole senza ORD.
Errore account_name	Accenti o lettere minuscole	Usa lettere MAIUSCOLE senza accenti, cifre, spazi, punti o trattini.
webhook_secret: 8–200 characters	Chiave troppo corta	Usa almeno 8 caratteri stampabili.
Il cliente non vede l'opzione	Non presente nell'interfaccia vietnamita, disattivato o nessun tasso	Controlla la lingua, l'interruttore e il tasso.
Cliente ha pagato ma nessun accredito	Webhook non arrivato, causale modificata, importo errato	Controlla il log dei webhook di Sepay; il bonifico risulterà sotto Unmatched transactions se la causale era errata.
Il webhook restituisce 401 o 403	Metodo di autenticazione o chiave non corrispondenti	Usa lo stesso metodo e la stessa chiave in Sepay e NexCMP.
Il cliente visualizza "Too many pending requests"	Limite ordini in sospeso raggiunto	Terminano o attendono la scadenza.