- Directives d'intégration
- Mise en œuvre d'une intégration Batch
Mise en œuvre d'une intégration Batch
Conditions préalables
- Vérifiez que votre profil de commerçant est activé pour le service Batch.
- Avant de commencer l'intégration, voir les bonnes pratiques et conseils.
Étapes d'intégration
Étape 1 : Accéder à la passerelle
Tout d'abord, vérifiez votre connectivité à Mastercard Gateway.
Étape 2 : Connaître vos champs de saisie
Avant de commencer à créer l'intégration, vous devez préparer les valeurs des champs de saisie.
Étape 3 : Créer une demande de batch
La création du corps de la demande est une étape essentielle dans l'intégration.
Étape 4 : Envoyer une demande de batch
Il existe de nombreux composants pour garantir l'envoi sécurisé du corps de la demande de transaction à Mastercard Gateway.
Étape 5 : Extraire le statut du batch
Une fois qu'un batch est soumis, vous pouvez périodiquement demander son état pour déterminer l'état actuel du traitement du batch.
Étape 6 : Traiter la réponse du batch
Une fois que le traitement d'un batch est terminé, vous pouvez demander un fichier de réponse contenant le résultat de chacune des opérations chargées.
Étape 7 : Test et mise en service
Les tests vous permettent de vérifier si votre intégration fonctionne comme vous le souhaitez.
Dépannage et questions fréquentes
Puis-je utiliser plusieurs profils de commerçants dans une seule demande de batch ?
Oui, vous pouvez utiliser plusieurs profils de commerçants dans une seule demande de batch si vous pouvez garantir que les informations d'identification de l'opération (identifiant du commerçant et mot de passe d'authentification) pour chaque ligne d'enregistrement de l'opération sont valides pour permettre une authentification et une autorisation réussies.
Par défaut, pour chaque opération d'un batch, les informations d'indentification de l'opération utilisent les informations d'authentification fournies dans l'en-tête de la demande de batch (identifiant et mot de passe du commerçant). Vous pouvez choisir d'utiliser le mécanisme par défaut ou de fournir les informations d'identification de l'opération pour chaque ligne d'enregistrement de l'opération. Pour la dernière option, l'authentification de l'opération utilise les informations d'identification de niveau de l'opération et ne sélectionne pas par défaut les informations d'identification de chargement de batch. Si les informations d'identification au niveau de l'opération sont incorrectes, le téléchargement du batch sera rejeté.
Dans l'exemple de fichier de batch ci-dessous, les opérations VOID (Annuler) utilisent les informations d'identification fournies dans l'en-tête de demande de batch, car l'identifiant et le mot de passe du commerçant n'ont pas été fournis.
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
Quelles sont les causes possibles d'échec d'une soumission de batch ?
Une soumission de batch peut échouer en raison des conditions d'erreur suivantes.
| Scénario | Message d'erreur |
|---|---|
| Batch incomplet en raison de la non-concordance du résumé du message SHA-1 | L'envoi du batch a échoué pour l'une des raisons suivantes :
|
Nom de batch en double
|
Échec de l'envoi du batch : un batch du même nom est en cours de chargement ou un batch du même nom mais avec un contenu différent a déjà été chargé. Si le fichier est en cours de chargement, veuillez patienter jusqu'à la fin de l'opération. Si vous utilisez un nom de fichier déjà pris, renommez le fichier et relancez la soumission. |
Une erreur d'authentification est renvoyée si vous ne disposez pas de privilèges suffisants pour soumettre des batches :
|
Échec de l'authentification : les informations d'identification fournies dans l'enregistrement <record number> sont incorrectes. Les raisons peuvent être les suivantes :
|
| Une erreur d'authentification est renvoyée si vous fournissez uniquement le mot de passe mais aucun ID de commerçant au niveau de l'opération. | Échec de l'authentification. L'enregistrement <record number> du fichier de batch comporte un mot de passe, mais pas d'ID de commerçant. Ajoutez un ID de commerçant ou supprimez le mot de passe pour utiliser les informations d'identification du commerçant au niveau du batch pour cet enregistrement, puis réessayer de soumettre la demande. |
| Une erreur d'authentification est renvoyée si les informations d'identification du batch ne sont pas formatées correctement. | Échec de l'authentification : les informations d'identification fournies dans l'en-tête :
|
Une erreur d'authentification est renvoyée si :
|
Échec de l'authentification : Les informations d'identification fournies pour le batch ne sont pas valides. corrigez les informations d'identification et réessayez de soumettre la demande. |
| Une erreur d'analyse est renvoyée si l'en-tête contient des caractères non valides. | Échec de l'envoi du batch : le batch n'a pas pu être analysé car l'en-tête contenait un caractère illégal. Les caractères autorisés sont les suivants :
|
| Une erreur d'analyse est renvoyée si une ligne d'enregistrement d'opération contient plus de valeurs que celles définies dans l'en-tête. | Échec de l'envoi du batch : le batch n'a pas pu être analysé parce que l'enregistrement <record number> contenait plus de valeurs qu'il n'en était défini dans l'en-tête. Corrigez le batch, puis réessayer de le soumettre. |
| Une erreur d'analyse est renvoyée si la taille maximale d'un champ individuel est dépassée ou si une erreur d'analyse inconnue s'est produite dans un enregistrement d'opération. | Échec de l'envoi du batch : le batch n'a pas pu être analysé en raison d'une erreur dans l'enregistrement <record number>. Assurez-vous que le batch est conforme au format de fichier et que vous utilisez le bon codage, puis essayez de soumettre à nouveau le batch. |
| Une erreur de codage est renvoyée si aucun codage n'a été fourni ou si le codage fourni n'est pas pris en charge. | Échec de la demande : le codage fourni n'est pas pris en charge. Les codages pris en charge sont UTF-8 et LATIN1. Soumettez à nouveau la demande en utilisant un codage pris en charge. |
| Le batch est introuvable | Échec de la demande : un batch portant ce nom est introuvable. Corrigez le nom du batch et soumettez à nouveau la demande. |
| Le contrôle de longueur pour la version fournie a échoué. | Échec de la demande : la version fournie n'est pas valide. Corrigez la version et soumettez à nouveau la demande. |
| La vérification de la longueur du nom de batch fourni a échoué. | Échec de la demande : le nom de batch fourni n'est pas valide. Corrigez le nom du batch et soumettez à nouveau la demande. |
| La vérification de la longueur de l'ID du commerçant fourni a échoué. | Échec de la demande : l'ID du commerçant fourni n'est pas valide. Corrigez l'ID de commerçant et soumettez à nouveau la demande. |
| Une erreur de passerelle s'est produite | La demande n'a pas pu être soumise à la passerelle en raison d'une erreur interne de celle-ci. Réessayez ultérieurement. |
Le traitement des opérations par Batch peut échouer en raison d'une défaillance des communications ou des systèmes due à l'une des erreurs suivantes :
- Une erreur due à une défaillance interne du système s'est produite.
- Une erreur s'est produite car les ressources du serveur étaient insuffisantes pour traiter la demande à ce moment-là.
- Une erreur s'est produite lors du traitement d'une transaction de vérification de Tokenization
Lorsque cela se produit et qu'il est possible de relancer une opération, Batch tente d'envoyer celle-ci pour traitement jusqu'à la réception d'une réponse ne pouvant pas faire l'objet d'une nouvelle tentative ou jusqu'à ce que la limite des tentatives soit atteinte.
Batch stocke les noms de batch et leur code d'intégrité du message (MIC) correspondant que vous avez chargés. Les batches portant un nom de batch précédemment soumis mais avec un contenu différent peuvent être identifiés et seront rejetés par Batch.
Il est également possible d'identifier les batches de nom et de contenu identiques soumis précédemment. Batch renvoie le même statut que pour le batch chargé précédemment. Ainsi, si le commerçant pense qu'il existe un problème de transmission, il peut vérifier que le batch a été chargé correctement vers Batch.
Les valeurs de la ligne d'en-tête d'une demande de batch soumise pour traitement ne peuvent contenir que des caractères figurant dans les noms de champ NVP DirectAPI. Les caractères suivants sont autorisés :
- Les caractères alphanumériques (a-z, A-Z, 0-9)
- Le point (.)
- Les crochets ([ ])
Batch rejette un batch en cas de détection d'erreurs d'analyse. L'analyse comprend la division du batch en lignes et des lignes en champs.
Une erreur d'analyse peut se produire dans les cas suivants :
- Un enregistrement d'opération contient plus de virgules que ce qui figure dans l'enregistrement d'en-tête.
- La taille de champ individuel maximale est atteinte.
Vous devez d'abord corriger ces erreurs avant de soumettre à nouveau le batch pour traitement.
Bonnes pratiques et conseils
Le service Batch ne garantit pas qu'il traitera les opérations dans le même ordre que celui spécifié dans le fichier de batch, le répartiteur Batch pouvant traiter les opérations en parallèle. Ce comportement peut également être attribué à la fonction de nouvel essai, c'est-à-dire que si certaines opérations d'un fichier de batch nécessitent un nouvel essai, les opérations qui sont prêtes seront traitées en premier, quel que soit l'ordre dans lequel elles sont spécifiées. Par exemple, même si des opérations ultérieures sont spécifiées après des opérations initiales [opération Capture (Collecter) suivie d'une opération Authorization (Autorisation), opération Void (Annuler) suivie d'une opération Pay (Payer)], l'opération Capture (Collecter) peut être effectuée avant l'opération opération Authorization (Autorisation) ou l'opération Void (Annuler) avant l'opération Pay (Payer).
Par conséquent, pour les opérations qui doivent suivre strictement un ordre donné, il est recommandé d'exécuter d'abord le batch d'opérations initial, d'attendre le fichier de réponse du batch et, en cas de succès, d'exécuter le batch d'opérations suivant.
La Tokenization stocke les détails des cartes dans un jeton. Pour utiliser Tokenization avec Batch, vous devez utiliser l'identifiant de jeton dans le fichier de batch, comme indiqué ci-dessous.
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
Les informations d'identification de l'opération incluent l'identifiant du commerçant et le mot de passe. Pour chaque opération d'un batch, les informations d'indentification d'opération utilisent par défaut les informations d'identification d'authentification fournies dans l'en-tête de la demande de batch (identifiant et mot de passe du commerçant). Toutefois, si vous spécifiez des valeurs pour ces deux champs dans les lignes d'enregistrement d'opération, l'authentification de l'opération utilisera les informations d'identification au niveau de l'opération, et non les informations d'identification par défaut du batch chargé.
Oui, vous pouvez traiter plusieurs types d'opérations dans un seul fichier de batch à condition qu'elles ne soient PAS liées à la même commande, c'est-à-dire qu'elles ne contiennent pas le même identifiant de commande. Le service Batch ne garantit pas qu'il traitera les opérations dans le même ordre que celui spécifié dans le fichier de batch, le répartiteur Batch pouvant traiter les opérations en parallèle. Ce comportement peut également être attribué à la fonction de nouvel essai, c'est-à-dire que si certaines opérations d'un fichier de batch nécessitent un nouvel essai, les opérations qui sont prêtes seront traitées en premier, quel que soit l'ordre dans lequel elles sont spécifiées. Par exemple, si des opérations Pay (Payer) et Void (Annuler) figurent dans le même fichier de batch, l'opération Void (Annuler) peut être effectuée avant l'opération Pay (Payer). Toutefois, si les opérations ne sont PAS liées à la même commande (c.-à-d. si elles contiennent des identificateurs de commande différents), vous pouvez placer plusieurs types d'opérations dans un même fichier de batch.
Oui, vous pouvez utiliser des sources multiples de détails de cartes dans un seul fichier de batch, à l'exception de l'identifiant de session de paiement. Pour plus d'informations sur les sources multiples, voir Sources multiples de détails de cartes.
Les opérations Authorize (Autoriser) de l'exemple ci-dessous utilisent des jetons au lieu des détails de la carte.
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,