Banküberweisung (Vietnam)

Wo im Admin: Finance › Payment channels › VN bank transfer (/payments/bank). Wechselkurs: Finance › Payment channels › Exchange rates (/payments/fx).

Funktion

Ermöglicht Kunden das Aufladen des USD-Guthabens durch eine normale Banküberweisung in vietnamesischen Dong. NexCMP zeigt einen VietQR-Code, die Kontodaten und einen eindeutigen Überweisungsverwendungszweck an; Sepay überwacht Ihr Bankkonto und ruft einen Webhook auf, wenn das Geld eintrifft, woraufhin NexCMP das Guthaben gutschreibt. Verwenden Sie dies, wenn Sie an Kunden in Vietnam verkaufen.

Wird nur in der vietnamesischen Oberfläche angezeigt

Die vietnamesische Bankoption wird einem Kunden nur angeboten, wenn das Portal auf Vietnamese angezeigt wird. Kunden in jeder anderen Sprache sehen sie niemals.

Anforderungen

Komponente	Anforderung
Bankkonto	Ein vietnamesisches Bankkonto (oder ein virtuelles Sepay-Konto, VA), das mit einem Sepay-Konto unter my.sepay.vn verbunden ist.
Sepay	Ein Sepay-Konto mit aktivierter Webhook-Integration.
Wechselkurs	Es muss ein USD-zu-VND-Kurs existieren: Aktualisieren Sie diesen zuerst unter Exchange rates. Ohne einen Kurs antwortet der Kanal mit fx_unavailable und Kunden können keine Überweisung starten.
Netzwerk	Ihr Panel muss über HTTPS erreichbar sein, damit Sepay https://<your-domain>/v1/billing/sepay/webhook aufrufen kann.
Abhängigkeiten	Währung und Wechselkurse.

Infrastruktur vorbereiten

Auf Sepay-Seite:

1. Verbinden Sie in my.sepay.vn Ihr Bankkonto (oder erstellen Sie eine VA) und stellen Sie sicher, dass Transaktionen angezeigt werden.
2. Llegen Sie das Memo-Präfix fest — 2 bis 5 Großbuchstaben, zum Beispiel PAY. NexCMP generiert den Verwendungszweck als Präfix gefolgt von 8 zufälligen Ziffern (zum Beispiel PAY48210937). Das Präfix darf kein ORD enthalten und sollte von keinem anderen System verwendet werden, das Geld auf dasselbe Konto empfängt.
3. Wenn Ihr Sepay-Konto eine Zahlungscodestruktur verwendet, registrieren Sie dort dasselbe Präfix, damit Sepay den Verwendungszweck erkennt.
4. Erstellen Sie den Webhook später, nachdem Ihnen die NexCMP-Seite die URL und den Schlüssel (Schritt 7 unten) bereitgestellt hat.

In NexCMP verbinden

1. Öffnen Sie Finance › Payment channels › Exchange rates und klicken Sie auf Update exchange rates, falls noch kein Kurs gespeichert wurde.

2. Öffnen Sie Finance › Payment channels › VN bank transfer (/payments/bank).

3. Füllen Sie unter Receiving account Folgendes aus:

   Feld	Beispiel	Regel
   Bank	VCB Vietcombank	Wählen Sie aus der Liste; die BIN wird automatisch ausgefüllt.
   Kontonummer	0123456789	4–24 Ziffern oder Großbuchstaben.
   Virtuelles Konto (VA — optional)		Falls festgelegt, überweisen Kunden auf das VA und der QR-Code zeigt es an.
   Kontoinhaber	NGUYEN VAN A	Keine Umlaute/Akzente, GROSSBUCHSTABEN, 2–60 Zeichen.
   Überweisungs-Memo-Präfix	PAY	2–5 Großbuchstaben, kein ORD.

4. Wählen Sie unter Webhook authentication die Auth method: HMAC-SHA256 (empfohlen) oder API key, und geben Sie den Webhook key / HMAC secret (8–200 Zeichen) ein. Optional können Sie das userapi token von Sepay eingeben; es wird nur verwendet, um Überweisungen abzugleichen, deren Webhook verloren ging.

5. Legen Sie unter Channel & limits die Limits fest (Standardwerte in Klammern): Min / order (10,000 VND), Max / order (200,000,000 VND), Order expiry (120 Minuten, 15–1440), Max pending orders / account (3, 1–10), Reconcile every (10 Minuten) sowie optional Allowed webhook IPs (kommagetrennt; leer bedeutet, dass die IP nur protokolliert wird).

6. Klicken Sie auf Save. Das rote Banner „Sepay not configured“ verschwindet, sobald Konto, Name, Präfix und Schlüssel gültig sind.

7. Kopieren Sie Webhook URL to paste into my.sepay.vn (beginnt mit https://<your-domain>/v1/billing/sepay/webhook) über Copy. Öffnen Sie in SePay die Webhook-Integration, fügen Sie die URL ein, wählen Sie denselben Authentifizierungstyp sowie Schlüssel und aktivieren Sie das Ereignis „money in“.

8. Klicken Sie auf Test connection. Schalten Sie dann Enable Sepay for clients (main site) ein und klicken Sie auf Save.

Webhook-Sicherheit

Methode	Was Sepay senden muss
HMAC-SHA256	Header X-SePay-Signature: sha256=<hex>, berechnet über "<X-SePay-Timestamp>.<raw body>"; der Zeitstempel kann um maximal 300 Sekunden abweichen.
API-Schlüssel	Header Authorization: Apikey <key>.

Es werden nur die Header überprüft (niemals der Body oder Query-String) und der Vergleich erfolgt in konstanter Zeit. Es werden ausschließlich eingehende Überweisungen (transferType = in) auf Ihr konfiguriertes Konto oder VA verwendet. Jede Sepay-Transaktion wird einmal gespeichert, sodass ein wiederholter Webhook niemals doppelt gutgeschrieben wird. NexCMP antwortet mit 200 {"success":true}, selbst wenn eine Transaktion bewusst ignoriert wird, und mit HTTP 5xx nur bei vorübergehenden Fehlern, damit Sepay es erneut versucht.

Wie der Kunde bezahlt

1. Unter Billing › Deposit (vietnamesische Benutzeroberfläche) wählt der Kunde die Option für vietnamesische Banküberweisungen sowie einen Betrag aus und klickt dann auf die Schaltfläche zum Erstellen der Überweisung.
2. NexCMP rechnet den USD-Betrag zum gespeicherten Kurs um (einschließlich der Marge und des Rundungsschritts, die Sie unter Exchange rates festgelegt haben) und rundet den VND-Betrag auf den Rundungsschritt auf.
3. Der Kunde sieht einen QR-Code (VietQR, lokal generiert) mit Kontonummer, Bank, Betrag und Verwendungszweck.
4. Nach der Überweisung ruft Sepay den Webhook auf, NexCMP schreibt floor(VND received × 100 / rate) Cent gut. Der Kurs wird beim Erstellen der Bestellung fixiert; geht das Geld nach Ablauf der Bestellung ein, wird der höhere Wert aus fixiertem und aktuellem Kurs verwendet.
5. Bestellungen laufen nach Order expiry ab; der Abgleich läuft alle Reconcile every Minuten als Sicherheitsnetz (erfordert das userapi-Token).

Verifizierung

1. Erstellen Sie als Kunde auf der vietnamesischen Benutzeroberfläche eine Testbestellung. Überprüfen Sie, ob Betrag, Konto und Verwendungszweck korrekt sind.
2. Überweisen Sie den kleinsten zulässigen Betrag mit dem exakten Verwendungszweck.
3. Innerhalb einer Minute zeigt das Portal die Einzahlung als abgeschlossen an und das Guthaben steigt; die State-Karte auf der Bankseite zeigt die Zeit des letzten Webhooks an.
4. Öffnen Sie Finance › Billing › Top-ups und überprüfen Sie, ob die Zahlung mit dem eingegangenen VND-Betrag aufgeführt ist.

Limits & Hinweise

• Minimum. Das VND-Minimum, das ein Kunde sieht, ist der größere Wert aus Min / order und dem VND-Wert der minimum top-up.
• Ausstehende Bestellungen. Ein Kunde kann nur Max pending orders / account offene Bestellungen haben (Standard: 3).
• Gleicher Verwendungszweck doppelt. Eine zweimalige Überweisung mit demselben Verwendungszweck erstellt eine zweite abgeschlossene Zahlung zum aktuellen Kurs.
• Keine automatische Rückerstattung auf ein Bankkonto.
• Gebühr. Der Kanal hat keine feste Gebührenzeile in Fees & limits; die Kursmarge ist die einzige Anpassung.
• Resellers können ihr eigenes Konto konfigurieren; ihre Webhook-URL endet mit /v1/billing/sepay/webhook/r/<id>.

Nicht zugeordnete Überweisungen

Geld, das auf dem Konto eingegangen ist, aber keinen gültigen Verwendungszweck trägt, erscheint unter Unmatched transactions unten auf der Seite (Filter All channel owners oder Master). Überprüfen Sie die Bankreferenz mit dem Kunden, klicken Sie dann auf Assign und wählen Sie das Konto aus. Das Guthaben wird zum aktuellen Kurs gutgeschrieben.

Fehlerbehebung

Symptom	Ursache	Behebung
Banner "SePay nicht konfiguriert"	Bank, Konto, Inhabername, Präfix oder Schlüssel fehlt oder ist ungültig	Füllen Sie die Karten Receiving account und Webhook authentication aus.
Banner "USD/VND-Kurs blockiert" (fx_unavailable)	Kein Wechselkurs gespeichert	Exchange rates › Update exchange rates ausführen.
prefix: 2–5 capital letters, no ORD	Präfix ungültig	Verwenden Sie 2–5 Großbuchstaben ohne ORD.
account_name-Fehler	Akzente oder Kleinbuchstaben	Verwenden Sie unakzentuierte GROSSBUCHSTABEN, Ziffern, Leerzeichen, Punkte oder Bindestriche.
webhook_secret: 8–200 characters	Schlüssel zu kurz	Verwenden Sie mindestens 8 druckbare Zeichen.
Kunde kann die Option nicht sehen	Nicht auf der vietnamesischen Oberfläche, ausgeschaltet oder kein Tarif	Überprüfen Sie die Sprache, den Schalter und den Tarif.
Kunde hat bezahlt, aber es wurde nichts gutgeschrieben	Webhook kam nicht an, Verwendungszweck geändert, falscher Betrag	Überprüfen Sie Sepays Webhook-Protokoll; der Transfer wird unter Unmatched transactions aufgeführt, wenn der Verwendungszweck falsch war.
Webhook gibt 401 oder 403 zurück	Authentifizierungsmethode oder Schlüssel stimmt nicht überein	Verwenden Sie dieselbe Methode und denselben Schlüssel in Sepay und NexCMP.
Kunde sieht "Too many pending requests"	Limit für ausstehende Bestellungen erreicht	Warten Sie, bis sie abgeschlossen sind oder ablaufen.