- Directives d'intégration
- Fonctionnalités prises en charge (données supplémentaires)
- Données supplémentaires
Données supplémentaires
DirectAPI vous permet de transférer des données supplémentaires dans les transactions. Il peut s'agir de données sectorielles concernant la compagnie aérienne, la santé ou les données liées à la transaction (Internet, commande, ou même données personnalisées). Les données supplémentaires que vous transférez pour une transaction sont stockées sur Mastercard Gateway dans cette transaction.
Les données de la compagnie aérienne comprennent des détails sur des vols (ou un ensemble de vols), la référence de réservation, l’itinéraire, les détails sur le billet, etc.
Vous pouvez spécifier des détails sur plusieurs passagers et étapes de voyage associés au billet. La numérotation des données de passager et d'étape de voyage commence à 0. Par exemple airline.itinerary.leg[0].<fieldname>. Vous devez utiliser des numéros consécutifs pour les étapes de voyage et les données de passager, et ne devez pas sauter un numéro ou en répéter.
Les données de la compagnie aérienne s’appliquent aux opérations Authorize (Autorisation), Pay (Payer) Capture (Collecter) et Refund (Rembourser). Si vous soumettez des données de la compagnie aérienne sur une transaction initiale et que ces mêmes données s'appliquent à des transactions suivantes pour la commande, vous devez soumettre les mêmes données de la compagnie aérienne sur chaque transaction suivante.
Référence de l'API Airline Data (Données de la compagnie aérienne) [REST][NVP]
Les données Internet comprennent des informations sur la source de la transaction pour les transactions de commerce électronique. Il s'agit, par exemple, de l'adresse e-mail du client, de son adresse IP, du nom d'hôte, etc. Elles facilitent le processus d'autorisation pour les transactions sans carte présente, car l'émetteur peut les utiliser pour évaluer le risque de la transaction.
Les données Internet ne s'appliquent qu'aux opérations Authorize (Autoriser) et Pay (Payer).
Référence de l'API Internet Data (Données Internet) [REST][NVP]
Les données de commande et de poste comprennent les informations sur la commande et les postes qu'elle contient. Vous pouvez indiquer ces informations dans la demande et choisir de les afficher au payeur (via les Hosted Checkout ou paiements avec redirection) avant de confirmer le paiement. Certaines données de commande et de poste, lorsqu'indiquées dans une transaction, peuvent qualifier la transaction pour des taux d’interchange plus intéressants avec les titulaires de cartes d'entreprise, professionnelles ou d'achat. Pour plus d'informations, voir Données de niveau II et de niveau III.
order.item[n].brand
order.item[n].category
order.item[n].description
order.item[n].name
order.item[n].quantity
Lorsqu'une quantité décimale et multipliée par des montants (order.item[n].unitPrice
,order.item[n].unitTaxAmount
ouorder.item[n].unitDiscountAmount
) et si les positions décimales dans la valeur calculée dépassent les unités mineures de la devise du payeur, la passerelle arrondit le total au moyen de l’algorithme « arrondir au nombre entier supérieur ». Par exemple, si 2,555 (quantité) fois 3 (prix unitaire) est égal à 7,665, et si la devise du payeur (USD) comporte 2 unités mineures, le montant arrondi du poste est 7,66.
Assurez-vous d’appliquer cet arrondi lorsque vous indiquez ces champs de montant dans la demande.order.item[n].sku
order.item[n].unitPrice
Ce montant est multiplié par
order.item[n].quantity
pour déterminer le montant d'article total pour le poste. Siorder.itemAmount
est indiqué, la somme du montant d'article total pour tous les postes DOIT être égale à la valeur figurant dansorder.itemAmount
.order.item[n].unitTaxAmount
Ce montant est multiplié par
order.item[n].quantity
pour déterminer le montant de taxe total pour le poste. Siorder.taxAmount
est indiqué, la somme du montant de taxe total pour tous les postes DOIT être égale à la valeur figurant dansorder.taxAmount
.order.item[n].unitDiscountAmount
Ce montant est multiplié par
order.item[n].quantity
pour déterminer le montant de remise total pour le poste. Siorder.discount.amount
est indiqué, la somme du montant de remise total pour tous les postes DOIT être égale à la valeur figurant dansorder.discount.amount
.
order.item[n].name
, order.item[n].quantity
et order.item[n].unitPrice
pour ce poste.order.currency
(obligatoire)order.id
order.description
order.shippingAndHandlingAmount
order.amount
(obligatoire)
Si vous ne renseignez pas ce champ mais indiquez l'un des montants de sous-totaux (
order.itemAmount
,order.shippingAndHandlingAmount
,order.taxAmount
,order.gratuityAmount
,order.cashbackAmount
) etorder.discount.amount
, ce montant est calculé comme étant la somme des montants de sous-totaux moins le montant de remise. Si vous renseignez ce champ et l'un des montants de sous-totaux, la valeur de ce champ DOIT être égale à la valeur calculée.order.itemAmount
Si vous ne renseignez pas ce champ mais indiquez des données pour un poste, ce montant est calculé comme étant la somme du montant total d'article (
order.item[n].unitPrice
xorder.item[n].quantity
) pour tous les postes. Si vous renseignez ce champ et les données de l'un des postes, la valeur de ce champ DOIT être égale à la valeur calculée.order.taxAmount
Si vous ne renseignez pas ce champ mais indiquez des données pour un poste, ce montant est calculé comme étant la somme du montant total de taxe (
order.item[n].unitTaxAmount
xorder.item[n].quantity
) pour tous les postes. Si vous renseignez ce champ et les données de l'un des postes, la valeur de ce champ DOIT être égale à la valeur calculée.order.discount.amount
Si vous ne renseignez pas ce champ mais indiquez des données pour un poste, ce montant est calculé comme étant la somme du montant total de remise (
order.item[n].unitDiscountAmount
xorder.item[n].quantity
) pour tous les postes. Si vous renseignez ce champ et les données de l'un des postes, la valeur de ce champ DOIT être égale à la valeur calculée.order.gratuityAmount
: montant que le payeur a choisi de donner en tant que gratification ou pourboire en plus du montant qu'il paie pour les biens ou les services qu'il vous achète. Le montant de pourboire est inclus dans le montant total de la commande que vous indiquez dans le champorder.amount
.order.cashbackAmount
: montant que le payeur a choisi de recevoir en espèces en plus du montant qu'il paie pour les biens ou les services qu'il vous achète. Le montant de remboursement est inclus dans le montant total de la commande que vous indiquez dans le champorder.amount
.
Les données de commande et de poste s'appliquent aux demandes Authorize (Autoriser), Pay (Payer), Initiate Browser Payment (Lancer un paiement avec redirection), Confirm Browser Payment (Confirmer un paiement avec redirection), Open Wallet (Ouvrir le portefeuille) et Hosted Checkout.
order.cashbackAmount et order.gratuityAmount ne s'appliquent qu'aux demandes Authorize (Autoriser) et Pay (Payer).
Référence de l'API Order Data (Données de commande) [REST][NVP]
Référence de l'API Line Item Data (Données de poste) [REST][NVP]
Les données personnalisées de l'acquéreur comprennent toutes les informations supplémentaires demandées par l'acquéreur qui ne peuvent pas être transmises en utilisant les autres champs de données disponibles. Les données personnalisées sont stockées dans la base de données, qui peut être utilisée pour créer des rapports extérieurs à Mastercard Gateway. Ce champ ne doit pas contenir de données sensibles.
Les données personnalisées de l’acquéreur peuvent être appliquées aux opérations Authorize (Autoriser), Capture (Collecter), Pay (Payer), Refund (Rembourser) et Void (Annuler).
Référence de l'API Acquirer Custom Data (Données personnalisées de l'acquéreur) [REST][NVP]
Les données personnalisées relatives aux risques comprennent toutes les informations supplémentaires demandées par les prestataires tiers en matière d'évaluation des risques externes qui ne peuvent pas être transmises en utilisant les autres champs de données disponibles. Les noms des champs personnalisés de risque doivent être entrés comme convenu avec votre prestataire tiers en matière d'évaluation des risques. Les champs de données personnalisées de risque sont retournés dans la réponse. Vous pouvez les utiliser afin de générer des rapports et d'effectuer des analyses selon les besoins. Aucune donnée sensible ne doit être incluse dans les champs de données personnalisées de risque.
Les données personnalisées de risque s'appliquent aux opérations Authorize (Autoriser), Capture (Collecter), Pay (Payer) et Verify (Vérifier).
Référence de l'API Acquirer Custom Data (Données personnalisées de l'acquéreur) [REST][NVP]
Les données personnalisées du commerçant comprennent toutes les informations supplémentaires qui vous intéressent et qui ne peuvent pas être transmises en utilisant les autres champs de données disponibles. Vous pouvez par exemple transmettre des données personnalisées du commerçant liées à une région de vente en utilisant order.custom.salesRegion, où « salesRegion » peut être n'importe quel champ que vous définissez. Les champs de données personnalisés sont retournés dans la réponse. Vous pouvez les utiliser afin de générer des rapports et effectuer des analyses selon les besoins.
Les données ne sont pas requises par Mastercard Gateway ou l’acquéreur pour traiter la transaction, et vous ne devez pas inclure des données sensibles dans tous les champs de données personnalisées du commerçant.
Les données personnalisées du commerçant s'appliquent aux opérations Authorize (Autoriser), Capture (Collecter), Pay (Payer), Refund (Rembourser), Void (Annuler), Verify (Vérifier), Referral (Renvoi), Update Authorization (Mettre à jour l'autorisation), Initiate Browser Payment (Lancer un paiement avec redirection), Confirm Browser Payment (Confirmer un paiement avec redirection) et Hosted Checkout.
Référence de l'API Merchant Custom Data (Données personnalisées du commerçant) [REST][NVP]
Vous pouvez soumettre des transactions de dette à la passerelle si votre prestataire de services de paiement vous a autorisé à rembourser une dette pour au moins une méthode de financement (CREDIT, DEBIT ou CHARGE). Si la passerelle n'est pas en mesure de déterminer la méthode de financement d'une transaction de remboursement de dette, la transaction est rejetée.
Lors de la soumission d'une transaction de remboursement de dette à la passerelle, vous devez indiquer un indicateur de dette et pouvez devoir indiquer des informations supplémentaires sur le bénéficiaire du paiement. Les données du bénéficiaire du paiement incluent des informations supplémentaires sur la personne qui reçoit les fonds. Ces données peuvent être envoyées à l'acquéreur et utilisées pour le risque lié au paiement et ainsi réduire les transactions frauduleuses.
Outre les champs standard pour une transaction Verify (Vérifier), Authorize (Autoriser) ou Pay (Payer), renseignez les champs suivants pour initier une transaction de remboursement de dette :
order.purchaseType
: Définissez ce champ sur DEBT_REPAYMENT. Ce champ est obligatoire.debtRepayment.paymentRecipient.accountIdentifier
debtRepayment.paymentRecipient.dateOfBirth
debtRepayment.paymentRecipient.lastName
debtRepayment.paymentRecipient.postcodeZip
Les données soumises sont retournées dans la réponse de transaction — la date de naissance et l'identifiant du compte sont masqués.
Référence de l'API Debt Repayment Indicator (Indicateur de remboursement de dette)[REST][NVP]
Vous pouvez indiquer des données relatives à la santé en tant que données de poste pour une commande. Les données relatives à la santé comportent notamment les détails des postes pour les achats liés à la santé, tels que des soins relatifs à la vue, des soins dentaires et des médicaments sur ordonnance ou autres achats (liés à des établissements de santé). Vous ne devez indiquer ces données que si elles vous concernent et si elles sont acceptées par votre acquéreur.
Si vous devez envoyer des données de santé, vous devez indiquer toutes les informations suivantes sur le poste de santé dans la transaction.
- Catégorie sectorielle : les catégories sectorielles prises en charge sont les suivantes : HEALTHCARE_VISION, HEALTHCARE_DENTAL, HEALTHCARE_PRESCRIPTION ou HEALTHCARE_OTHER.
- Catégorie (facultative) : sous-catégorie pour la catégorie sectorielle. Par exemple, lunettes sur ordonnance pour HEALTHCARE_VISION
- Nom de l'article
- Prix unitaire de l'article
- Quantité de l'article
- Montant de taxe unitaire de l'article
Mastercard Gateway envoie à l'acquéreur la somme des montants pour tous les postes ayant la même catégorie sectorielle. Le montant d'un poste est calculé comme suit : (Item Unit Price + Item Unit Tax Amount) * Item Quantity
. Un seul enregistrement est envoyé à l'acquéreur pour chaque catégorie sectorielle.
La somme de toutes les valeurs de la catégorie sectorielle est envoyée en tant que montant de l'article pour la commande. Si le montant de la commande est différent du montant de l'article, la transaction est refusée.
Les données relatives à la santé peuvent être soumises dans des transactions Authorize (Autoriser), Pay (Payer), Capture (Collecter) et Refund (Rembourser).
Référence de l'API Healthcare Data (Données relatives à la santé)[REST][NVP]
Les données du descripteur de déclaration (également appelées données du descripteur dynamique) comportent notamment les informations de contact que vous indiquez pour impression sur les relevés de compte du payeur. Ces données sont soumises à l'acquéreur et remplacent les données du descripteur enregistrées chez l'acquéreur. Si vous indiquez des données du descripteur de déclaration partielles sur une transaction, l'acquéreur complètera les données du relevé en utilisant les données du descripteur enregistrées chez lui.
Si vous devez envoyer des données du descripteur de déclaration, vous pouvez indiquer les informations de contact de votre entreprise suivantes dans la transaction.
- Adresse complète du commerçant
- Nom du commerçant
- Numéro de téléphone de l'entreprise du commerçant
Les données soumises sont retournées dans la réponse de transaction.
Les données du descripteur de déclaration peuvent être soumises dans des opérations Authorize (Autoriser), Pay (Payer), Capture (Collecter), Refund (Rembourser), Verify (Vérifier), Update Session (Mettre à jour la session) et Pay with Session (Payer avec une session) uniquement.
Référence de l'API Statement Descriptor Data (Données du descripteur de déclaration)[REST][NVP]
Les données de croisière incluent des informations sur la croisière, les passagers de la croisière et peuvent également inclure des données relatives à d'autres secteurs d'activité, la compagnie aérienne ou la location de voiture, par exemple, si les achats les concernant ont été faits dans le cadre d'un forfait croisière.
Si vous devez envoyer des données de croisière, vous pouvez indiquer les informations suivantes sur la croisière dans la transaction.
cruise.bookingReference
- Champs
cruise.company.address.*
cruise.company.contact.customerServicePhone
cruise.company.contact.companyPhone
cruise.travelAgentCode
cruise.travelAgentName
cruise.travelPackageItems
cruise.departureDate
cruise.returnDate
cruise.shipName
- Champs
cruise.passenger[n].*
Les données de croisière peuvent être soumises dans les opérations Authorize (Autoriser), Pay (Payer), Capture (Collecter), Refund (Rembourser), Create Checkout Session (Créer une session de paiement) et Update Session (Mettre à jour la session).
Les données soumises sont retournées dans la réponse de transaction.
Référence de l'API Cruise Data (Données de croisière)[REST][NVP]
Si vous êtes commerçant et soumettez des transactions impliquant l'achat de crypto-monnaies ou de valeurs à risque élevé, vous devez en informer l'émetteur en renseignant certains indicateurs dans votre demande de transaction à la passerelle.
L'indicateur de crypto-monnaie s'applique uniquement aux commerçants dont le code de catégorie du commerçant (MCC) est 6051 (Quasi Cash - Merchant or Non-Financial Institutions - Foreign Currency, Non-Fiat Currency) qui traitent des transactions par carte Mastercard, Maestro ou Visa. L'indicateur de valeurs à risque élevé s'applique uniquement aux commerçants dont le MCC est 6211 (Securities - Brokers/Dealers) qui traitent des transactions Mastercard ou Maestro.
Outre les champs standard pour une transaction Verify (Vérifier), Authorize (Autoriser), Pay (Payer), renseignez le champ order.purchaseType
pour indiquer une transaction de valeurs à risque élevé ou de crypto-monnaie. Vous pouvez définir le champ avec l'une des valeurs suivantes :
CRYPTOCURRENCY
: si vous êtes commerçant avec un MCC 6051 (Quasi Cash - Merchant or Non-Financial Institutions - Foreign Currency, Non-Fiat Currency) et cette transaction concerne l'achat de crypto-monnaie.HIGH_RISK_SECURITIES
: si vous êtes commerçant avec un MCC 6211 (Securities - Brokers/Dealers) et cette transaction concerne l'achat de valeurs à risque élevé.
Référence de l'API High-Risk Securities and Cryptocurrency Indicator Data (Données sur les indicateurs de valeurs à risque élevé et de crypto-monnaie)[REST][NVP]
Sur Mastercard Gateway, les transactions qui impliquent de débiter de l'argent d'un compte pour en créditer un autre sont appelées transactions de financement de compte. Le bénéficiaire peut être la même personne, une autre personne ou une organisation. Si votre MSO (Merchant Service Organization) a activé cette fonctionnalité pour vous, vous pouvez faciliter les types de transaction de financement de compte suivants pour vos clients :
- De personne à personne
- Transfert de fonds intraorganisationnels
- Transfert de fonds interorganisationnels
- 6540 (Transaction de financement),
- 4829 (Transfert d'argent) et
- 6538 (Transactions de financement pour MoneySend).
Les MCC suivants ne peuvent être utilisés que pour le traitement du code 00 ou 20 :
- 6538 (Transactions de financement pour MoneySend),
- 6540 (Transaction de financement), et
- 4829 (Transfert d'argent).
Les données de transaction de financement de compte (TAF) comprennent notamment les informations sur le type d'émetteur, le type de bénéficiaire, le type de compte du bénéficiaire, la méthode de financement de compte et l'objet du financement. Elles peuvent également inclure d'autres informations sur le bénéficiaire. Lorsqu'il vous est demandé de fournir des données de transaction de financement de compte, vous devez indiquer, selon le type de transaction que vous soumettez, tout ou partie des informations ci-dessous sur la transaction.
accountFunding.senderType:
ce champ peut prendre les valeurs PERSON, COMMERCIAL_ORGANIZATION, NON_PROFIT_ORGANIZATION et GOVERNMENT.accountFunding.senderIsRecipient:
définit si l'émetteur et le destinataire de la transaction de financement de compte sont identiques ou différents. Si aucune valeur n'est indiquée, ce champ prend la valeur par défaut, FALSE.accountFunding.recipient.account.fundingMethod:
ce champ peut prendre les valeurs CHARGE, CREDIT et DEBIT. Si aucune valeur n'est indiquée, ce champ prend la valeur par défaut, UNKNOWN.accountFunding.recipient.stateProvinceCode:
code de l'état ou de la province du destinataire. La valeur doit correspondre à la deuxième partie du code ISO 3166-2. Par exemple :- Pour les commerçants situés aux États-Unis, indiquez le code d'État ISO 3166-2 à 2 lettres.
- Pour les bases militaires américaines, indiquez l'un des codes suivants : AE, AA ou AP.
- Pour une adresse au Canada, indiquez le code de province ISO 3166-2 à 2 lettres.
accountFunding.recipient.account:
détails sur le compte du bénéficiaire qui recevra ultérieurement les fonds que vous avez débités de l'expéditeur dans cette transaction.accountFunding.purpose:
ce champ peut prendre les valeurs CRYPTOCURRENCY_PURCHASE, MERCHANT_SETTLEMENT et PAYROLL. Si aucune valeur n'est indiquée, il prend la valeur par défaut, OTHER.accountFunding.recipient:
détails sur le bénéficiaire qui recevra les fonds.accountFunding.recipient.account.identifierType:
ce champ peut prendre les valeurs CARD_NUMBER, BANK_ACCOUNT_NATIONAL, BANK_ACCOUNT_BIC, BANK_ACCOUNT_IBAN, EMAIL_ADDRESS, PHONE_NUMBER, SOCIAL_NETWORK_PROFILE_ID et STAGED_WALLET_USER_ID. Si aucune valeur n'est indiquée, il prend la valeur par défaut, OTHER.accountFunding.recipient.account.identifier:
identifiant du compte du bénéficiaire du paiement, par exemple, numéro de carte ou numéro de compte bancaire.accountFunding.recipient.firstName:
prénom du bénéficiaire du paiement.accountFunding.recipient.lastName:
nom du bénéficiaire du paiement.accountFunding.recipient.country:
pays du bénéficiaire du paiement.accountFunding.recipient.postCodeZip:
code postal du bénéficiaire du paiement.accountFunding.recipient.dateOfBirth:
date de naissance du bénéficiaire du paiement au format aaaa-mm-jj.accountFunding.reference:
référence de la transaction de financement de compte. Cette référence est générée par Mastercard Payment Gateway.
Les données des transactions de financement de compte peuvent être soumises dans les opérations Authorize (Autoriser), Authenticate_Payer (Authentifier le payeur), Capture (Collecter), Create_Checkout_Session (Créer une session de paiement), Pay (Payer), Refund (Rembourser), Standalone Capture (Collecte autonome), Standalone refund (Remboursement autonome), Update Session (Mettre à jour la session) et Verify (Vérifier). Les données soumises sont retournées dans la réponse de transaction.
Référence de l'API Account Funding Transactions Data (Données des transactions de financement de compte)[REST][NVP]
Sélectionnez le MCC approprié pour l'indicateur Type de transaction si l'organisme d'origine est enregistré pour le service Mastercard MoneySend et soumet le message de demande d'autorisation pour les transactions de financement et les remboursements de transaction de financement. Pour plus d'informations, consultez le guide de référence rapide sur MC Connect > Technical Resource Center (TRC) ou contactez votre banque acquéreuse pour obtenir les MCC recommandés pour différents types de transaction.
Intégration des transactions de financement du compteEnvoyez l'indicateur Type de transaction approprié lors de l'intégration avec les transactions de financement de compte en vous assurant que le MCC approprié et le champ de demande correct figurent dans l'API. La MSO vous a permis de soumettre des transactions de financement de compte et a configuré les types de transaction de financement de compte que vous êtes autorisé à soumettre. Pour plus d'informations sur le MCC, les champs de demande et la configuration de la MSO, consultez la documentation d'intégration MPGS ou contactez le support MPGS pour obtenir une aide supplémentaire.
Ce tableau décrit les MCC pour les transactions de financement initiées par les clients.
Identifiant du type de transaction
|
MCC 4829 - Transfert d'argent
|
MCC 6540 - Transaction de financement
|
MCC 6538 - Transactions de financement pour MoneySend
|
Virement général de personne à personne |
Valide pour F07 |
Valide pour F07 |
Valide pour C07 |
Virement de personne à compte de carte |
Valide pour F08 |
Valide pour F08 |
- |
Le tableau ci-dessous décrit les MCC pour les transferts initiés par des clients ou des organisations.
Identifiant du type de transaction |
MCC 4829 - Transfert d'argent |
MCC 6540 - Transaction de financement |
MCC 6538 - Transactions de financement pour MoneySend |
Virement sur le compte de débit ou prépayé de l'émetteur |
Valide pour F64 |
Valide pour F64 |
- |
Paiement de la facture de carte de crédit de l'émetteur |
Valide pour F54 |
Valide pour F54 |
Valide pour C54 |
Virement sur le compte de portefeuille numérique échelonné de l'émetteur |
Valide pour F61 |
Valide pour F61 |
- |
Virement général sur le compte de l'émetteur |
Valide pour F52 |
Valide pour F52 |
Valide pour C52 |
Virement général sur le compte de l'émetteur initié par des organisations |
Valide pour F52 |
Valide pour F52 |
Valide pour C52 |
Virement sur le portefeuille numérique échelonné de l'émetteur initié par des organisations |
Valide pour F61 |
Valide pour F61 |
- |
Virement sur le compte de carte de débit ou prépayée de l'émetteur initié par des organisations |
Valide pour F64 |
Valide pour F64 |
- |
Paiement de la facture de carte de crédit de l'émetteur initié par des organisations |
Valide pour F54 |
Valide pour F54 |
- |
Décaissement d'entreprise |
Valide pour F55 |
Valide pour F55 |
Valide pour C55 |
Décaissement d'un organisme gouvernemental/à but non lucratif |
- |
- |
Valide pour C56 |
Règlement rapide du commerçant |
- |
- |
Valide pour C57 |
Vitement général d'entreprise à entreprise |
Valide pour F65 |
Valide pour F65 |
Valide pour C65 |