Envoyer une demande
Suivez ces étapes pour envoyer une demande à Direct Payment pour une opération de transaction :
Étape 1 : Vérifier la connectivité de la passerelle
Avant d'envoyer des demandes, vérifiez votre connectivité à la passerelle. Pour ce faire, accédez à l'URL suivante via un navigateur Web : https://ap-gateway.mastercard.com/api/rest/version/1/information. Si la tentative de connexion réussit et que la passerelle traite les demandes, la page du navigateur affiche {"status":"OPERATING"}.
Étape 2 : Configurer votre méthode d'authentification
La passerelle prend en charge deux méthodes d'authentification : les certificats Secure Sockets Layer (SSL) et les mots de passe.
- Sélectionnez la méthode qui correspond le mieux à votre modèle économique et mettez-la en œuvre.
Étape 3 : Créer la demande de transaction
La création du corps de la demande est une étape essentielle dans votre intégration. Les champs du corps de la demande recueillis à partir du formulaire destiné au payeur et générés dans votre système sont soumis à l'URL de l'API au format REST JSON. En fonction de l'opération de transaction, l'une des méthodes HTTP suivantes est utilisée dans l'URL :
- POST, lorsque vous souhaitez que le système crée une nouvelle collecte.
- PUT, lorsque vous souhaitez ajouter ou modifier un membre d'une collecte.
- GET, pour extraire les opérations.
Formater les données du corps de la demande à partir des formulaires
Quelle que soit la langue sélectionnée dans l'extrait de code, il est important que votre intégration formate correctement les données de la demande de transaction. Dans de nombreuses langues, il est courant de recevoir les données saisies par le payeur dans un formulaire sous forme de tableau.
Dans la plupart des cas, vous pouvez ensuite utiliser un tableau pour stocker les noms et valeurs de chaque champ que vous souhaitez transmettre à la passerelle et le formater comme illustré dans l'extrait suivant. Cet extrait de code remplit deux fonctions essentielles pour produire un corps de demande de transaction correctement formaté :
- Garantit qu'aucun champ vide n'est ajouté au corps de la demande de transaction.
- Formate les données selon le protocole JSON.
Comment convertir des données de formulaire en
(, ) ModifierÉtape 4 : Envoyer la demande de transaction
Suivez ces étapes pour vous assurer que le corps de la demande de transaction est envoyé en toute sécurité à la passerelle de paiement :
Définir les données d'authentification
L'API exige que chaque demande de transaction soit authentifiée avec succès. Si vous utilisez le mot de passe de l'API comme méthode d'authentification, l'extrait suivant explique comment fournir les données d'authentification, telles que l'ID du commerçant ou le mot de passe de l'API, ou les deux, sous forme d'en-tête dans chaque demande de transaction.
Définir les en-têtes HTTP
Les en-têtes HTTP fournissent des métadonnées concernant la demande de transaction envoyée à la passerelle. Outre les en-têtes d'authentification traités dans les sections précédentes, l'extrait suivant montre comment définir les en-têtes HTTP obligatoires pour chaque demande de transaction.
Les en-têtes Content-Length et Content-Type sont essentiels car ils indiquent au serveur Web le nombre et le type d'octets de données, identifiés par un type MIME.
Le codage des caractères de votre demande doit inclure le format ISO-8859-1 ou UTF-8. La passerelle rejette tous les caractères qui ne peuvent pas être représentés dans l'un des formats pris en charge. Si cela n'est pas spécifié, la passerelle utilise par défaut le codage ISO-8859-1. Voici un exemple d'en-tête Content-Type.
"Content-Type: application/json; charset=UTF-8"
Pour définir l'en-tête, utilisez le code suivant.
Utiliser une méthode HTTP spécifique
Il est important d'utiliser une méthode HTTP spécifique telle que POST, PUT ou GET pour chaque transaction. Toutes les opérations de base effectuées via l'API utilisent le protocole HTTP et les méthodes POST ou PUT, à l'exception de CHECK GATEWAY (Vérifier la passerelle) et de différentes opérations d'extraction :
La méthode HTTP PUT met à jour le membre adressé de la collection ou, s'il n'existe pas, crée un nouveau membre. Prenons l'exemple d'une demande dont la valeur de l'URI de la demande est : http://example.com/version/v1/merchant/m1/order/o1/transaction/t1
Dans l'URI, t1 est membre de la ressource de collecte o1. Si t1 existe, la demande modifie la ressource t1 ; sinon, elle crée un nouveau membre t1.
La méthode HTTP GET extrait une représentation du membre adressé de la collection. Prenons l'exemple d'une demande dont la valeur de l'URI de la demande est : http://example.com/version/v1/merchant/m1/order/o1/transaction/t1
La demande extrait le membre t1 de la ressource de collecte o1.
- La méthode HTTP POST crée une nouvelle collection. Dans les API de la passerelle, elle est principalement utilisée pour les opérations qui créent un nouvel jeu de données, comme l'opération CREATE SESSION (Créer une session) ou PAYMENT OPTIONS INQUIRY (Demande d'options de paiement).
L'extrait de code suivant montre comment utiliser la méthode HTTP POST.
L'extrait de code suivant montre comment utiliser la méthode HTTP PUT.
Définir l'URL de destination
L'URL utilisée pour envoyer la demande de transaction varie pour chaque opération de transaction. Dans l'extrait suivant, la fonction calcule l'URL à partir de votre configuration, définit les valeurs de la version et de la ressource du commerçant, et enfin ajoute une liste personnalisée de ressources et leurs identifiants.
Ces composants personnalisés représentent les ressources de la commande et de la transaction. Pour plus d'informations sur le format d'URL de chaque opération, voir les opérations individuelles dans la Référence API.
Définition de l'URL d'envoi d'une transaction
L'extrait de code suivant montre comment définir l'URL pour envoyer une transaction.
Vérifier le certificat SSL d'une passerelle
Si vous utilisez la méthode d'authentification par certificat SSL, validez le certificat SSL de la passerelle. La validation du certificat SSL lors de l'envoi de la demande de transaction permet d'éviter les attaques malveillantes et d'autres problèmes de sécurité potentiels. L'extrait de code suivant montre comment vérifier le certificat SSL.
Configurer un serveur proxy
Dans certains environnements de réseau, il peut être nécessaire d'envoyer la demande de transaction via un serveur proxy. Contactez votre administrateur réseau ou votre prestataire de services d'hébergement Web pour savoir si un serveur proxy est requis pour votre intégration. L'extrait de code suivant montre comment définir un proxy et son authentification.
Envoyer la transaction à la passerelle
Envoyez la demande de transaction correctement formatée à la passerelle et attendez une réponse. L'extrait de code suivant montre comment envoyer une transaction à la passerelle.