Virement bancaire (Vietnam)

Où trouver dans l'admin : Finance › Payment channels › VN bank transfer (/payments/bank). Taux de change : Finance › Payment channels › Exchange rates (/payments/fx).

Description

Permet aux clients de recharger le portefeuille USD par virement bancaire normal en dongs vietnamiens. NexCMP affiche un code VietQR, les détails du compte et un libellé de virement unique ; Sepay surveille votre compte bancaire et appelle un webhook lorsque l'argent arrive, puis NexCMP crédite le portefeuille. Utilisez cette option si vous vendez à des clients au Vietnam.

Affiché uniquement dans l'interface vietnamienne

L'option bancaire vietnamienne n'est proposée au client que lorsque le portail est affiché en Vietnamese. Les clients utilisant une autre langue ne la voient jamais.

Prérequis

Élément	Prérequis
Compte bancaire	Un compte bancaire vietnamien (ou un compte virtuel Sepay, VA) relié à un compte Sepay sur my.sepay.vn.
Sepay	Un compte Sepay avec l'intégration des webhooks activée.
Taux de change	Un taux USD/VND doit exister : mettez-le d'abord à jour sous Exchange rates. Sans taux, le canal renvoie fx_unavailable et les clients ne peuvent pas initier de virement.
Réseau	Votre panneau doit être accessible en HTTPS pour que Sepay puisse appeler https://<your-domain>/v1/billing/sepay/webhook.
Dépendances	Devise et taux de change.

Préparer l'infrastructure

Du côté de Sepay :

1. Sur my.sepay.vn, connectez votre compte bancaire (ou créez un VA) et assurez-vous que les transactions apparaissent.
2. Définissez le préfixe de libellé — 2 à 5 lettres majuscules, par exemple PAY. NexCMP génère le libellé sous la forme du préfixe suivi de 8 chiffres aléatoires (par exemple PAY48210937). Le préfixe ne doit pas contenir ORD et ne doit pas être utilisé par un autre système recevant des fonds sur le même compte.
3. Si votre compte Sepay utilise une structure de code de paiement, enregistrez le même préfixe afin que Sepay reconnaisse le libellé.
4. Créez le webhook ultérieurement, après que la page NexCMP vous a fourni l'URL et la clé (étape 7 ci-dessous).

Connecter dans NexCMP

1. Ouvrez Finance › Payment channels › Exchange rates et cliquez sur Update exchange rates si aucun taux n'a été enregistré.

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

3. Dans Receiving account, renseignez :

   Champ	Exemple	Règle
   Banque	VCB Vietcombank	Choisissez dans la liste ; le BIN se remplit automatiquement.
   Numéro de compte	0123456789	4 à 24 chiffres ou lettres majuscules.
   Compte virtuel (VA — facultatif)		S'il est défini, les clients effectuent le virement vers le VA et le QR code l'affiche.
   Nom du titulaire du compte	NGUYEN VAN A	Sans accents, EN MAJUSCULES, 2 à 60 caractères.
   Préfixe du libellé de virement	PAY	2 à 5 lettres majuscules, sans ORD.

4. Dans Webhook authentication, choisissez Auth method : HMAC-SHA256 (recommandé) ou API key, et saisissez la Webhook key / HMAC secret (8 à 200 caractères). Saisissez éventuellement le userapi token de Sepay ; il est utilisé uniquement pour rapprocher les virements dont le webhook a été perdu.

5. Dans Channel & limits, définissez les limites (par défaut entre parenthèses) : Min / order (10,000 VND), Max / order (200,000,000 VND), Order expiry (120 minutes, 15–1440), Max pending orders / account (3, 1–10), Reconcile every (10 minutes) et, optionnellement, Allowed webhook IPs (séparées par des virgules ; vide pour consigner uniquement).

6. Cliquez sur Save. La bannière rouge « Sepay not configured » disparaît dès que le compte, le nom, le préfixe et la clé sont valides.

7. Copiez Webhook URL to paste into my.sepay.vn (qui indique https://<your-domain>/v1/billing/sepay/webhook) avec Copy. Dans Sepay, ouvrez l'intégration de webhook, collez l'URL, choisissez le même type d'authentification et la même clé, puis activez l'événement « money in ».

8. Cliquez sur Test connection. Activez ensuite l'option Enable Sepay for clients (main site) et cliquez sur Save.

Sécurité des webhooks

Méthode	Ce que Sepay doit envoyer
HMAC-SHA256	En-tête X-SePay-Signature: sha256=<hex>, calculé sur "<X-SePay-Timestamp>.<raw body>" ; l'horodatage peut différer d'au maximum 300 secondes.
Clé API	En-tête Authorization: Apikey <key>.

Seuls les en-têtes sont vérifiés (jamais le corps ni la chaîne de requête) et la comparaison est à temps constant. Seuls les transferts entrants (transferType = in) vers votre compte configuré ou VA sont utilisés. Chaque transaction Sepay est enregistrée une seule fois, de sorte qu'un webhook relancé ne crédite jamais deux fois. NexCMP répond 200 {"success":true} même lorsqu'il ignore délibérément une transaction, et HTTP 5xx uniquement pour les erreurs temporaires afin que Sepay réessaie.

Comment le client paie

1. Dans Billing › Deposit (interface en vietnamien), le client choisit l'option de virement bancaire vietnamien et un montant, puis clique sur le bouton de création de virement.
2. NexCMP convertit le montant en USD au taux enregistré (incluant la marge et l'étape d'arrondi que vous avez définies dans Exchange rates) et arrondit le montant en VND vers le haut selon l'étape d'arrondi.
3. Le client voit un code QR (VietQR, généré localement) avec le numéro de compte, la banque, le montant et le libellé.
4. Après le transfert, Sepay appelle le webhook, NexCMP crédite floor(VND received × 100 / rate) centimes. Le taux est verrouillé lors de la création de la commande ; si l'argent arrive après l'expiration de la commande, le plus élevé entre le taux verrouillé et le taux actuel est utilisé.
5. Les commandes expirent après Order expiry ; la réconciliation s'exécute toutes les Reconcile every minutes en tant que filet de sécurité (nécessite le jeton userapi).

Vérification

1. Créez une commande test en tant que client sur l'interface vietnamienne. Vérifiez que le montant, le compte et le libellé sont corrects.
2. Transférez le montant minimum autorisé avec le libellé exact.
3. En moins d'une minute, le portail affiche le dépôt comme terminé et le solde augmente ; la carte State sur la page de la banque indique l'heure du dernier webhook.
4. Ouvrez Finance › Billing › Top-ups et vérifiez que le paiement est répertorié avec le montant en VND reçu.

Limites et notes

• Minimum. Le minimum en VND qu'un client voit est le plus élevé entre Min / order et la valeur en VND du minimum top-up.
• Commandes en attente. Un client ne peut avoir que Max pending orders / account commandes ouvertes (par défaut 3).
• Même libellé deux fois. Transférer deux fois avec le même libellé crée un second paiement complété au taux actuel.
• Pas de remboursement automatique vers un compte bancaire.
• Frais. Le canal n'a pas de ligne de frais fixes dans Fees & limits ; la marge sur le taux est le seul ajustement.
• Les Resellers peuvent configurer leur propre compte ; l'URL de leur webhook se termine par /v1/billing/sepay/webhook/r/<id>.

Transferts non appariés

L'argent qui est parvenu sur le compte mais ne comporte aucun libellé valide apparaît dans Unmatched transactions au bas de la page (filtre All channel owners ou Master). Vérifiez la référence bancaire avec le client, puis cliquez sur Assign et sélectionnez le compte. Le portefeuille est crédité au taux actuel.

Dépannage

Symptôme	Cause	Solution
Bannière "Sepay not configured"	Banque, compte, nom du titulaire, préfixe ou clé manquant ou invalide	Complétez les cartes Receiving account et Webhook authentication.
Bannière "USD/VND rate blocked" (fx_unavailable)	Aucun taux de change enregistré	Exchange rates › Update exchange rates.
prefix: 2–5 capital letters, no ORD	Préfixe invalide	Utilisez 2 à 5 lettres majuscules sans ORD.
Erreur account_name	Accents ou minuscules	Utilisez des lettres majuscules sans accent, des chiffres, des espaces, des points ou des tirets.
webhook_secret: 8–200 characters	Clé trop courte	Utilisez au moins 8 caractères imprimables.
Le client ne voit pas l'option	Non présent dans l'interface vietnamienne, désactivé ou taux manquant	Vérifiez la langue, le commutateur et le taux.
Client a payé mais rien n'a été crédité	Le webhook n'est pas arrivé, le mémo a changé, montant erroné	Consultez le journal des webhooks de Sepay ; le virement figurera dans Unmatched transactions si le mémo était incorrect.
Le webhook renvoie 401 ou 403	Incompatibilité de méthode d'authentification ou de clé	Utilisez la même méthode et la même clé dans Sepay et NexCMP.
Le client voit "Too many pending requests"	Limite de commandes en attente atteinte	Elles se terminent ou attendent l'expiration.