Le passage radical d'une économie monétaire à une économie numérique au Vietnam a établi un nouveau contexte, dans lequel les portefeuilles électroniques ne sont plus de simples outils de paiement mais deviennent une super application (Super App) qui joue un rôle central dans le comportement des consommateurs. MoMo, en tant que plateforme leader, a construit un écosystème technique complexe mais unifié, offrant aux entreprises des solutions allant du paiement en ligne au paiement de gré à gré en passant par des modèles de marketing intelligent et de gestion financière d'entreprise. L'intégration du système de paiement MoMo dans les opérations commerciales n'est pas seulement une exigence technique mais une décision stratégique pour atteindre un réseau de plus de 50 millions d'utilisateurs et traiter en moyenne plus d'un million de transactions par jour. Selon l'analyse des experts de Tan Phat Digital, ce rapport fournit une vue approfondie, complète et pratique du processus d'intégration de MoMo, des aspects juridiques, de l'architecture du système aux protocoles de sécurité et aux procédures opérationnelles post-intégration.
Chapitre 1 : Vue d'ensemble de l'architecture et de la position stratégique de MoMo dans l'écosystème Fintech
La position de MoMo est renforcée par de fortes capacités technologiques et une grande adaptabilité aux changements du marché. Le système de MoMo est conçu pour garantir la continuité des activités et une capacité système exceptionnelle. Les solutions de MoMo ne se limitent pas aux paiements en ligne, mais s'étendent également aux appareils IoT, à l'AIoT et aux solutions qui ne nécessitent pas d'intégration profonde (non-intégration), répondant aux besoins de tous les types d'entreprises, des microentreprises aux sociétés multinationales.
1.1. Indicateurs de croissance et force du réseau
La confiance des partenaires dans MoMo se manifeste par des chiffres de croissance stables. Partager des parts de marché au sein d'un réseau en forte croissance est une opportunité pour les entreprises d'optimiser leurs revenus et de minimiser les obstacles au paiement pour les clients.
Nombre d'utilisateurs actifs : Plus de 50 000 000 de personnes. Signification : Capacité à accéder à un énorme marché potentiel.
Nombre moyen de transactions : Plus de 1 000 000 de transactions/jour. Signification : Le système fonctionne de manière stable et fiable.
Partenaires en ligne (marchands en ligne) : Plus de 1 000 entreprises. Signification : Large réseau de connexion.
Points d'acceptation de paiement (Offline Outlets) : Plus de 50 000 points. Signification : Capacité à couvrir les canaux de vente physiques.
Système d'agents et de partenaires : Plus de 910 000 agents et 626 000 partenaires. Signification : Infrastructure pour prendre en charge les dépôts/retraits et des services financiers denses.
1.2. Classification des solutions d'intégration de base
MoMo propose une large gamme de produits, permettant aux entreprises de choisir la méthode qui convient à leurs ressources et à leur modèle économique. Tan Phat Digital identifie cette flexibilité comme la clé de l'optimisation de l'expérience client (UX) sur chaque point de contact.
Passerelle de paiement (Passerelle de paiement) : La solution tout-en-un (AiO) permet d'intégrer une variété de méthodes de paiement telles que le portefeuille MoMo, la carte ATM nationale, la carte internationale (VISA/Master/JCB) et les sources d'argent postpayées via un seul processus de connexion.
Paiements automatisés : Prend en charge le paiement en un clic avec authentification unique, adapté aux services d'abonnement récurrents.
SDK pour améliorations (MDK - MoMo Customized SDK) : Kit de développement logiciel optimisé pour une intégration approfondie dans les applications mobiles partenaires, offrant des performances de haute qualité et une expérience fluide.
IoT et AIoT Solutions : Solutions pour les appareils intelligents tels que les distributeurs automatiques, les kiosques, les SmartTV ou les points de vente à double écran, prenant en charge à la fois la reconnaissance faciale et la lecture de codes QR.
Solutions sans intégration : Pour les entreprises ne disposant pas d'une équipe technique solide, y compris un code QR statique et un lien de paiement par lien à barres à envoyer par SMS ou sur les réseaux sociaux.
Chapitre 2 : Enregistrement du profil d'entreprise et stratégie d'authentification (M4B)
Pour établir une présence officielle dans l'écosystème MoMo, les entreprises doivent passer par le portail d'administration MoMo for Business (M4B). Il ne s'agit pas simplement d'une procédure administrative mais d'une étape fondamentale pour établir les paramètres techniques d'identification et gérer ultérieurement la trésorerie.
2.1. Processus d'enregistrement d'un compte M4B
Le processus commence à business.momo.vn. Les entreprises doivent renseigner toutes les informations de leur compte, notamment leur nom de connexion (utilisé pour rechercher des informations) et leur mot de passe haute sécurité (de 8 à 18 caractères). Pour les entreprises ayant utilisé des plateformes de gestion telles que Haravan, Sapo ou CukCuk, l'enregistrement d'un compte M4B est une étape obligatoire pour obtenir les paramètres de connexion API.
La feuille de route standardisée depuis l'enregistrement jusqu'à l'opération officielle (Go-live) est résumée par Tan Phat Digital à travers des étapes strictes :
Enregistrement d'un profil marchand (Merchant) Profile).
Intégration technique sur l'environnement de test. (Sandbox).
Terminer les tests SIT (System Integration Testing) sur l'environnement de test.
Effectuer l'authentification du compte professionnel via des documents juridiques.
Demander des informations d'identification (informations d'identification) pour l'environnement réel (production).
Effectuer les tests d'acceptation de l'utilisateur (UAT) sur l'environnement de production et approbation finale. requis.
Approuvé et officiellement déployé le service.
2.2. Documents juridiques et exigences d'authentification
La fourniture de documents précis détermine la rapidité d'approbation par les équipes d'assurance qualité et juridiques de MoMo. Les exigences en matière de documentation comprennent :
Pour les entreprises : Licence d'enregistrement d'entreprise originale (GPKD) ou copie notariée, image claire.
Pour les ménages d'entreprises individuelles : Carte d'identité/CCCD du représentant (photo recto et verso, sans coins flous ni coupés).
L'unité n'en possède pas. Licence commerciale : Carte d'identité/CCCD et informations sur le propriétaire du magasin (applicable aux petits modèles, sans statut juridique complet).
Documents supplémentaires : Logo de la marque (format 100x100 pixels), Document de paiement des taxes, Procuration.
Une caractéristique importante du système M4B est la prise en charge de la signature de contrats électroniques, aidant à accélérer le processus d'intégration sans avoir à se rencontrer en personne. face.
Chapitre 3 : Architecture technique de la solution API unifiée tout-en-un (AiO)
La solution API unifiée AiO de MoMo représente la standardisation de la connectivité de paiement. Au lieu d'avoir à maintenir plusieurs flux de connexion pour différents types de cartes et fonds, les partenaires n'ont besoin que de déployer une seule API.
3.1. Paramètres d'identifiant de connexion (Credentials)
Dans un environnement intégré, les partenaires travailleront avec un ensemble de clés de sécurité. La différence entre les environnements de test et de production réside dans ces valeurs clés et l'adresse du serveur (domaine).
Code partenaire : Identifiant unique de l'entreprise dans le système MoMo.
Clé d'accès : Clé utilisée pour accorder l'accès au système API de MoMo.
Clé secrète : Clé secrète utilisée pour créer des signatures électroniques Signature pour chaque requête HTTP. Il s'agit du composant le plus important pour garantir l'intégrité des données.
Clé publique : utilisée dans les algorithmes de chiffrement de données RSA pour les solutions nécessitant une sécurité plus élevée.
3.2. Configuration de l'infrastructure et du réseau (liste blanche IP)
Le système MoMo nécessite que les partenaires configurent des pare-feu pour permettre à des plages d'adresses IP spécifiques de communiquer avec les serveurs partenaires :
Environnement sandbox (Test) : Domaine
test-payment.momo.vn. IP entrante :210.245.113.71. IP sortante :118.69.210.244,118.68.171.198.Environnement de production : Domaine
payment.momo.vn. IP entrante :118.69.212.158. IP sortante :118.69.210.244,116.103.110.134(mis à jour le 11 septembre 2024).
Chapitre 4 : Mécanisme de sécurité et protocole de signature numérique
La sécurité des informations sur les transactions est une priorité absolue dans les systèmes Fintech. MoMo utilise des signatures numériques pour authentifier les données, garantissant que les informations n'ont pas été modifiées par des tiers.
4.1. Algorithme HMAC-SHA256
MoMo utilise l'algorithme de hachage HMAC-SHA256 pour créer des signatures. Il s'agit d'un algorithme symétrique, utilisant la même clé secrète pour le calcul. Formule :
Signature = HMAC_SHA256(SecretKey, RawString)
4.2. Règles de création de chaînes brutes
Tri des paramètres : Les noms de champs (noms de clés) doivent être classés par ordre alphabétique de
a-z.Format de chaîne : Concaténez les paires
key=valueensemble, séparées par les caractères&.Hachage des données : Utilisez la clé secrète pour hacher la chaîne nouvellement créée. Le résultat est une chaîne hexadécimale de 64 caractères.
Remarque de Tan Phat Digital : Ne révélez absolument jamais la clé secrète dans le code source côté client (Frontend). La création de signature doit toujours être effectuée côté serveur.
Chapitre 5 : Processus d'intégration technique des paiements uniques (API captureWallet)
Il s'agit du flux de paiement le plus courant, y compris l'initiation de la transaction, la navigation des utilisateurs et le traitement des résultats.
5.1. Initier le paiement
Le serveur partenaire envoie une requête HTTP POST au point de terminaison MoMo avec les paramètres : partnerCode, requestId, amount (Min 1 000 VND), orderId, orderInfo, redirectUrl, ipnUrl, requestType (captureWallet) et extraData.
5.2. Navigation et expérience utilisateur
Après un appel API réussi, MoMo renvoie un JSON contenant :
lien profond : Ouvre directement l'application MoMo (optimisation App-to-App).
payUrl : URL de la page de paiement sur le navigateur (optimisation Web pour ordinateur de bureau/mobile).
qrCodeUrl : Données pour créer un code QR affiché sur place.
Chapitre 6 : Mécanisme de notification instantanée de paiement (IPN)
IPN est un mécanisme important qui garantit la synchronisation via la communication de serveur à serveur, même si l'utilisateur perd la connexion après le paiement.
Principe : MoMo envoie HTTP POST à
ipnUrl. La charge utile contientresultCode,transId,amountetsignature.Traitement du serveur : nécessite une validation de signature, une vérification de
orderId/amountet une réponse avec le code HTTP 204 (Aucun contenu) dans les 15 heures. secondes.
Chapitre 7 : Gestion du statut et opérations post-paiement
Vérifier le statut : Utilisé lorsque l'IPN ou les résultats de navigation ne sont pas reçus après 30 secondes.
Remboursement : Applicable en cas de transaction réussie. Notez que le remboursement
orderIddoit être un nouveau code.Annuler la transaction (inverse) : Payez immédiatement lorsque la transaction est en attente ou en cas d'erreur technique du côté du partenaire.
Chapitre 8 : Écosystème MoMo Mini App - Stratégie "App-in-App"
MoMo Mini App permet aux entreprises de déployer des applications Web directement sur MoMo. plate-forme, permet d'atteindre une vaste base d'utilisateurs sans investir dans une application indépendante sur le Store.
Chapitre 9 : Solutions de paiement hors ligne et appareils de point de vente
MoMo étend les capacités de paiement dans l'espace physique via :
Code statique QR (QR statique) : Le plus simple, les clients scannent le code et saisissent eux-mêmes le montant.
Code QR dynamique : POS génère un code QR unique pour chaque facture, les clients n'ont qu'à scanner et confirmer.
Chapitre 10 : Contrôle des doublons et immuabilité (idempotence)
MoMo utilise le champ requestId (l'UUID V4 doit être utilisé) pour contrôler les doublons pendant 31 jours. Si le même requestId est reçu, le système renvoie l'ancien résultat au lieu de déduire à nouveau l'argent.
Chapitre 11 : Système de codes d'erreur et stratégie de gestion des exceptions
2xx : Traitement réussi.
4xx : Erreur de contrepartie (mauvaise signature, paramètres manquants numéro).
5xx : Erreur du système MoMo.
Code 0 : Succès.
Code 1001 : Fonds insuffisants.
Code 1006 : L'utilisateur annule.
Chapitre 12 : Processus de test SIT et UAT
Cette phase utilise l'environnement Sandbox et l'MoMo Test App. Le compte de portefeuille de test par défaut a un mot de passe/OTP de 000000. Il est nécessaire de tester les flux réussis, les flux d'erreur (pas assez d'argent, QR expiré) et les flux de sécurité (montant de la modification).
Chapitre 13 : Exemple de code source de référence (exemples de code)
Vous trouverez ci-dessous un exemple de code source exécutable compilé par Tan Phat Digital pour aider les partenaires à se déployer rapidement.
13.1. Node.js
JavaScript
// paramètres
var code partenaire = "MOMO" ;
var accessKey = "F8BBA842ECF85";
var secretkey = "K951B6PE1waDMi640xX08PD3vg6EkVlz";
var requestId = PartnerCode + new Date().getTime();
var orderId = requestId;
var orderInfo = "payer avec MoMo";
var redirectUrl = "https://momo.vn/return";
var ipnUrl = "https://callback.url/notify";
montant var = "50 000" ;
var requestType = "captureWallet"
var extraData = "";
// construction signature brute
var rawSignature = "accessKey="+accessKey+"&amount=" + montant+"&extraData=" + extraData+"&ipnUrl=" + ipnUrl+"&orderId=" + orderId+"&orderInfo=" + orderInfo+"&partnerCode=" + PartnerCode +"&redirectUrl=" + redirectUrl+"&requestId=" + requestId+"&requestType=" + requestType
const crypto = require('crypto');
var signature = crypto.createHmac('sha256', clé secrète)
.update (signature brute)
.digest('hexadécimal');
const requestBody = JSON.stringify({
code partenaire : code partenaire,
clé d'accès : clé d'accès,
ID de demande : ID de demande,
montant : montant,
ID de commande : ID de commande,
commandeInfo : commandeInfo,
URL de redirection : URL de redirection,
ipnUrl : ipnUrl,
extraData : extraData,
requestType : requestType,
signature :signature,
langue : 'fr'
});
const https = exiger('https');
options const = {
nom d'hôte : 'test-payment.momo.vn',
port: 443,
chemin : '/v2/gateway/api/create',
méthode : 'POST',
en-têtes : {
'Type de contenu' : 'application/json',
'Content-Length' : Buffer.byteLength (requestBody)
}
}
const req = https.request(options, res => {
res.setEncoding('utf8');
res.on('données', (corps) => {
console.log('payUrl: ' + JSON.parse(body).payUrl);
});
})
req.write(requestBody);
req.end();
13.2. Go (Golang)
Go
paquet principal
importer (
"octets"
"crypto/hmac"
"crypto/sha256"
"encodage/hexadécimal"
"encodage/json"
"fmt"
"net/http"
"strconv"
"github.com/sony/sonyflake"
)
tapez la structure de charge utile {
Chaîne PartnerCode `json:"partnerCode"`
Chaîne AccessKey `json:"accessKey"`
Chaîne RequestID `json:"requestId"`
Chaîne de montant `json:"montant"`
Chaîne d'ID de commande `json:"orderId"`
Chaîne OrderInfo `json:"orderInfo"`
Chaîne de redirectionUrl `json:"redirectUrl"`
Chaîne IpnUrl `json:"ipnUrl"`
Chaîne ExtraData `json:"extraData"`
Chaîne RequestType `json:"requestType"`
Chaîne de signature `json:"signature"`
}
fonction main() {
flocon := sonyflake.NewSonyflake(sonyflake.Settings{})
a, _ := flocon.NextID()
b, _ := flocon.NextID()
var orderId = strconv.FormatUint(a, 16)
var requestId = strconv.FormatUint(b, 16)
var point de terminaison = "https://test-payment.momo.vn/v2/gateway/api/create"
var secretKey = "PPuDXq1KowPT1ftR8DvlQTHhC03aul17"
var charge utile = Charge utile{
Code partenaire : "MOMOIQA420180417",
Clé d'accès : "SvDmj2cOTYZmQQ3H",
ID de demande : ID de demande,
Montant : "1000",
ID de commande : ID de commande,
Info commande : "momo tout-en-un",
URL de redirection : "https://webhook.site/...",
IpnUrl : "https://webhook.site/...",
Données supplémentaires : "",
Type de requête : "captureWallet",
}
var rawSignature octets.Buffer
rawSignature.WriteString("accessKey=" + payload.AccessKey + "&amount=" + payload.Amount + "&extraData=" + payload.ExtraData + "&ipnUrl=" + payload.IpnUrl + "&orderId=" + payload.OrderID + "&orderInfo=" + payload.OrderInfo + "&partnerCode=" + payload.PartnerCode + "&redirectUrl=" + payload.RedirectUrl + "&requestId=" + payload.RequestID + "&requestType=" + payload.RequestType)
h := hmac.New(sha256.New,byte(secretKey))
h.Write(rawSignature.Bytes())
payload.Signature = hex.EncodeToString(h.Sum(nil))
jsonPayload, _ := json.Marshal(charge utile)
resp, _ := http.Post(endpoint, "application/json", bytes.NewBuffer(jsonPayload))
var résultat map[string]interface{}
json.NewDecoder(resp.Body).Decode(&résultat)
fmt.Println("PayUrl est : ", résultat["payUrl"])
}
13.3. Python
Python
importer json
importer l'uuid
demandes d'importation
importer hmac
importer du hashlib
point final = "https://test-payment.momo.vn/v2/gateway/api/create"
code partenaire = "MOMO"
clé d'accès = "F8BBA842ECF85"
clé secrète = "K951B6PE1waDMi640xX08PD3vg6EkVlz"
orderInfo = "payer avec MoMo"
redirectUrl = "https://webhook.site/..."
ipnUrl = "https://webhook.site/..."
montant = "50000"
orderId = str(uuid.uuid4())
requestId = str(uuid.uuid4())
requestType = "captureWallet"
données supplémentaires = ""
rawSignature = "accessKey=" + accessKey + "&amount=" + montant + "&extraData=" + extraData + "&ipnUrl=" + ipnUrl + "&orderId=" + orderId + "&orderInfo=" + orderInfo + "&partnerCode=" + PartnerCode + "&redirectUrl=" + redirectUrl + "&requestId=" + requestId + "&requestType=" + requestType
h = hmac.new (octets (secretKey, 'ascii'), octets (rawSignature, 'ascii'), hashlib.sha256)
signature = h.hexdigest()
données = {
'partenaireCode' : partenaireCode,
'requestId' : requestId,
'montant' : montant,
'ID de commande' : ID de commande,
'commandeInfo' : commandeInfo,
'URL de redirection' : URL de redirection,
'ipnUrl' : ipnUrl,
'lang' : "vi",
'extraData' : extraData,
'type de demande' : type de demande,
'signature' : signature
}
données = json.dumps (données)
réponse = request.post(endpoint, data=data, headers={'Content-Type': 'application/json'})
print(response.json()['payUrl'])
13.4. Ruby
Ruby
nécessite 'net/https'
nécessite 'uri'
nécessite 'json'
nécessite 'openssl'
exiger 'securerandom'
point final = "https://test-payment.momo.vn/v2/gateway/api/create"
code partenaire = "MOMO"
clé d'accès = "F8BBA842ECF85"
clé secrète = "K951B6PE1waDMi640xX08PD3vg6EkVlz"
montant = "50000"
orderId = SecureRandom.uuid
requestId = SecureRandom.uuid
rawSignature = "accessKey="+accessKey+"&amount="+amount+"&extraData=&ipnUrl=...&orderId="+orderId+"&orderInfo=...&partnerCode="+partnerCode+"&redirectUrl=...&requestId="+requestId+"&requestType=captureWallet"
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secretKey, rawSignature)
jsonRequête = {
:partnerCode => partenaireCode,
:requestId => requestId,
:montant => montant,
:orderId => orderId,
:signature => signature,
:requestType => "captureWallet"
}
uri = URI.parse (point final)
http = Net :: HTTP.new (uri.host, uri.port)
http.use_ssl = vrai
request = Net::HTTP::Post.new(uri.path, {'Content-Type' => 'application/json'})
request.body = jsonRequest.to_json
réponse = http.request(requête)
met JSON.parse(response.body)["payUrl"]
13.5. PHP (Initialisation et IPN)
PHP
// Initier le paiement
$partnerCode, 'requestId' => $requestId, 'amount' => $amount, 'orderId' => $orderId, 'orderInfo' => $orderInfo, 'redirectUrl' => $redirectUrl, 'ipnUrl' => $ipnUrl, 'extraData' => $extraData, 'requestType' => $requestType, 'signature' => $signature);
$result =executePostRequest($endpoint, json_encode($data));
$jsonResult = json_decode($result, true);
header('Emplacement : '. $jsonResult['payUrl']);
?>
// Gestion des IPN
13.6. C# (.NET)
C#
// MoMoSecurity.cs
en utilisant System.Security.Cryptography ;
en utilisant System.Text ;
espace de noms MoMo {
classe MoMoSecurity {
chaîne publique signSHA256 (message de chaîne, clé de chaîne) {
octet keyByte = Encoding.UTF8.GetBytes(key);
octets messageBytes = Encoding.UTF8.GetBytes(message);
using (var hmacsha256 = new HMACSHA256(keyByte)) {
octet hashmessage = hmacsha256.ComputeHash(messageBytes);
chaîne hex = BitConverter.ToString(hashmessage);
return hex.Replace("-", "").ToLower();
}
}
}
}
//MoMoForm.cs
point de terminaison de chaîne = "https://test-payment.momo.vn/v2/gateway/api/create" ;
chaîne PartnerCode = "MOMO5RGX20191128" ;
chaîne accessKey = "SvDmj2cOTYZmQQ3H" ;
chaîne clé secrète = "PPuDXq1KowPT1ftR8DvlQTHhC03aul17" ;
string orderId = Guid.NewGuid().ToString();
chaîne requestId = Guid.NewGuid().ToString();
montant de la chaîne = "50 000" ;
// Construire rawHash par ordre alphabétique...
MoMoSecurity crypto = nouveau MoMoSecurity();
signature de chaîne = crypto.signSHA256(rawHash, clé secrète) ;
// Envoi d'une requête HTTP Post...
L'intégration de MoMo ne consiste pas simplement à installer un mode de paiement, mais à un parcours complet de transformation numérique. En se conformant aux normes techniques en matière de signature, d'IPN et de sécurité des clés, les entreprises peuvent non seulement créer un système de paiement fiable, mais également établir une solide confiance avec les clients à l'ère numérique d'aujourd'hui. Le succès de l'intégration réside dans la combinaison de précision technique et de flexibilité dans les stratégies opérationnelles commerciales d'unités réputées telles que Tan Phat Digital.
Partager
