- Directives d'intégration
- Fonctionnalités prises en charge (Modes de paiement)
- Paiements par titulaire de la carte présent
Titulaire de la carte présent
Les paiements par titulaire de la carte présent (CHP) font référence à des transactions utilisant un terminal de point de vente (PDV). Le terminal peut lire les données de la carte par :
- lecture d'une carte EMV
- technologie NFC (Near Field Communication) à partir d'une carte sans contact
- lecture d'une carte avec bande magnétique
- saisie du numéro de carte
La prise en charge des méthodes ci-dessus n'est disponible que pour DirectAPI version 40 et ultérieure.
Un paiement CHP est initié par un terminal et envoyé à la passerelle en tant que transaction Verify (Vérifier), Authorize (Autoriser), Capture (Collecter), Pay (Payer) ou Refund (Rembourser). Par exemple, les transactions autorisées hors ligne par la puce figurant sur la carte sont envoyées en tant que transaction Capture (Collecter) uniquement et les transactions nécessitant une autorisation de la part de l'émetteur utilisent une transaction Authorize (Autoriser) en ligne, suivie d'une transaction Capture (Collecter).
Les transactions CHP interagissent avec de nombreuses autres fonctionnalités de la passerelle. Vous pouvez :
- créer un jeton pour la carte,
- rembourser à l'aide de la même intégration que vos transactions de commerce électronique ou via l'IU,
- unifier les rapports de commerce électronique et CHP.
Conditions préalables
Les transactions en présence de titulaire de carte doivent être activées par votre Your payment service provider et par votre acquéreur.
Champs communs utilisés pour les transactions CHP
Les champs d'API suivants sont pertinents pour toutes les intégrations avec titulaire de la carte présent via la passerelle.
transaction.source=CARD_PRESENT: si vous ne renseignez pas ce champ, la source de transaction par défaut configurée sur votre lien d'acquéreur par votre your payment service provider sera utilisée. [REST][NVP]- numéro de carte : le numéro de carte est obligatoire, mais, suivant la manière dont la carte est lue, par saisie clavier, bande magnétique ou puce EMV, vous pouvez l'indiquer dans :
sourceOfFunds.provided.card.numberpour les transactions saisies.sourceOfFunds.provided.card.track1et/ousourceOfFunds.provided.card.track2pour les transactions par bande magnétique ou
les équivalents de la balise EMV, balise 56 et balise 57, respectivement, fournis danssourceOfFunds.provided.card.emvRequestpour les transactions sans contact où les données de la carte sont dans le format de la bande magnétique.- La balise 5A dans
sourceOfFunds.provided.card.emvRequestpour les transactions EMV (avec/sans contact) où les données de la carte sont dans le format EMV. sourceOfFunds.provided.card.p2pe.payloadpour les transactions P2PE (Point-to-Point Encryption) où les données de la carte sont au format crypté DUKPT.
- identifiant du terminal : L'identifiant du terminal est obligatoire, mais, suivant la manière dont la carte est lue, par saisie clavier, bande magnétique ou puce EMV, vous pouvez l'indiquer dans :
posTerminal.lanepour les transactions saisies et les transactions par bande magnétique.- La balise 9F1C dans
sourceOfFunds.provided.card.emvRequestpour les transactions EMV (avec/sans contact) où les données de la carte sont au format EMV.
Assurez-vous que les champs de terminal PDV suivants sont correctement définis, en fonction de la manière dont le terminal génère les données de carte pour la transaction. Si les données pour ces champs sont disponibles, vous devez toujours les indiquer. La passerelle transmettra les données à l'acquéreur, comme requis. Si l'acquéreur demande un champ et si celui-ci n'est pas présent, la transaction échouera.
posTerminal.addressposTerminal.attended: Si vous ne renseignez pas ce champ, la passerelle utilise par défaut la valeurUNKNOWN_OR_UNSPECIFIEDposTerminal.authorizationMethodposTerminal.cardHolderActivated: Si vous ne renseignez pas ce champ, la passerelle utilise par défaut la valeurNOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability: Ce champ est obligatoire pour les transactions EMV.posTerminal.location: Ce champ est obligatoire pour les transactions EMV.posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: Ce champ est obligatoire pour les transactions par puce et les transactions d'actions de secours par puce (notamment les annulations) pour toutes les transactions en ligne.posTerminal.serialNumberposTerminal.mobile.cardInputDevice: Ce champ s'applique aux appareils POS mobiles (mPOS), lorsque l'appareil accepte la saisie du code PIN par appuis ou à l'aide d'un clavier physique. Le logiciel du code PIN ne doit être utilisé que pour les appareils n'ayant pas de clavier permettant de prendre en charge le code PIN. Pour les exigences en matière d'intégration mPOS, voir Intégration en vue d'utiliser mPOS.order.gratuityAmount: Renseignez ce champ si le paiement inclut un montant de pourboire.
[REST][NVP]order.cashbackAmount: Renseignez ce champ si le paiement inclut un montant de remise.
[REST][NVP]order.cashAdvance: Renseignez ce champ si le paiement inclut un montant d'avance en espèces.
[REST][NVP]
Référence de l'API POS Terminal (Terminal de point de vente) [REST][NVP]
Traiter une transaction EMV
Si les données de la carte ont été lues à partir de la puce de la carte (carte EMV uniquement),
- Demandez ces balises EMV au terminal (balises prises en charge par la passerelle).
- Indiquez les balises retournées dans le champ
sourceOfFunds.provided.card.emvRequesten tant qu'objet JSON dans un protocole REST ou en tant qu'ensemble de champs dans un protocole NVP (accepté si le terminal ne fournit pas toutes les balises EMV prises en charge).Les valeurs de balise EMV doivent être formatées exactement comme retournées par le terminal — les valeurs binaires doivent être représentées en format hexadécimal. - Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
sourceOfFunds.provided.card.emvRequest [REST][NVP]
Certaines des balises EMV prises en charge correspondent aux concepts de paiement de base, comme le numéro de compte principal. Ces concepts apparaissent également en tant que champ de demande d'API, comme sourceOfFunds.provided.card.number. Dans la documentation de référence d'API, la description de ces champs de demande d'API correspondants indique leurs liens. Par exemple, la description du champ sourceOfFunds.provided.card.number comporte le texte « Ce champ correspond à la balise EMV 5A ».
Si vous indiquez des données en tant que balise EMV, vous n'avez pas besoin d'indiquer ces mêmes données en tant que champ de demande d'API. La passerelle renseigne les champs de demande d'API correspondants avec les valeurs fournies dans les balises EMV, lorsqu'elles existent, et utilise ces valeurs pour tous les traitements internes, les messages de l'acquéreur et les réponses des transactions. Par exemple, si vous envoyez sourceOfFunds.provided.card.emvRequest.9F1C avec la valeur « Lane_03 », posTerminal.lane avec la valeur « Lane_03 » est envoyé à l'acquéreur et retourné dans la réponse de la transaction.
Si requis, vous pouvez choisir d'indiquer les balises EMV et les champs de demande d'API correspondants dans la demande de transaction. Voir Utilisation avancée : Données de transaction dans les balises EMV et les champs de la demande de l'API.
Vous trouverez ci-dessous un exemple de demande EMV dans REST pour une collecte autonome, où l'autorisation a été effectuée hors ligne sur le terminal.
| URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Méthode HTTP | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"currency": "EUR",
"amount": "10.99",
"source": "CARD_PRESENT"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"expiry": {
"month": "1",
"year": "39"
},
"emvRequest": {
"82": "0000",
"95": "0000000000",
"9F02": "000000001099",
"9A": "161021",
"5F2A": "840",
"9F1A": "840",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F34": "1E0300",
"9F36": "0002",
"9C": "00",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F37": "2A4E1690",
"9F33": "E0B8C8"
}
}
}
},
"posTerminal": {
"inputCapability": "CONTACTLESS_CHIP",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"lane": "Lane_03",
"attended": "ATTENDED",
"serialNumber":"123456789",
"onlineReasonCode":"FORCED_BY_MERCHANT",
"cardPresenceCapability":"CARD_PRESENT",
"authorizationMethod":"OFFLINE",
"address":
{
"country":"IRL",
"city":"Dublin"
}
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 10.99,
"creationTime": "2017-06-06T09:42:54.280Z",
"currency": "EUR",
"id": "sa-dfc1b030-4520-48ec-a7e0-889999d7e4ab",
"status": "CAPTURED",
"totalAuthorizedAmount": 10.99,
"totalCapturedAmount": 10.99,
"totalRefundedAmount": 0
},
"posTerminal": {
"address": {
"city": "Dublin",
"country": "IRL"
},
"attended": "ATTENDED",
"authorizationMethod": "OFFLINE",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "Lane_03",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"onlineReasonCode": "FORCED_BY_MERCHANT",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"serialNumber": "123456789"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"emvRequest": {
"82": "0000",
"95": "0000000000",
"5F2A": "840",
"9A": "161021",
"9C": "00",
"9F02": "000000001099",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "840",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F36": "0002",
"9F37": "2A4E1690"
},
"emvResponse": {
"4D3E": "456",
"5A2F": "123"
},
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-06-06T09:42:54.280Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 10.99,
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "1706063974",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "CAPTURE"
},
"version": "43"
}
Vous trouverez ci-dessous une liste des balises EMV prises en charge par la passerelle. Si l'une de ces balises est retournée par le terminal, incluez-la dans le champ sourceOfFunds.provided.card.emvRequest.
Balise EMV |
Nom |
Obligatoire |
|---|---|---|
| 4F | Nom de l'identifiant de l'application (AID) | - |
| 56 | Piste 1 | - |
| 57 | Données équivalentes de la piste 2 | - |
| 5A | Numéro de séquence PAN (Application Primary Account) |
- |
| 5F24 | Date d'expiration de l'application | - |
| 5F25 | Date d'entrée en vigueur de l'application | - |
| 5F28 | Code de pays de l'émetteur | - |
| 5F2A | Code devise de la transaction | - |
| 5F34 | Numéro de séquence PAN (Application Primary Account) |
- |
| 82 | Profil d'échange entre applications (AIP) | Oui |
| 84 | Nom du fichier dédié | - |
| 87 | Indicateur de priorité de l'application | - |
| 95 | Résultat de la vérification du terminal (TVR) | Oui |
| 9A | Date de la transaction | Oui |
| 9B | Informations sur le statut de la transaction | - |
| 9C | Type de transaction | Oui |
| 9F02 | Montant autorisé | Oui |
| 9F03 | Montant de remise | - |
| 9F06 | Identifiant de l'application (AID) - Terminal | - |
| 9F07 | Contrôle de l'utilisation de l'application | - |
| 9F08 | Numéro de version de l'application - ICC | - |
| 9F09 | Numéro de version de l'application - Terminal | - |
| 9F0D | Code d'action de l'émetteur - Valeur par défaut | - |
| 9F0E | Code d'action de l'émetteur - Refus | - |
| 9F0F | Code d'action de l'émetteur - En ligne | - |
| 9F10 | Données d'application de l'émetteur (IAD) | Oui |
| 9F1A | Code pays du terminal | Oui |
| 9F1C | Identification du terminal | - |
| 9F1E | Numéro de série du périphérique d'interface (IFD) | - |
| 9F21 | Heure de la transaction | - |
| 9F26 | Cryptogramme de l'application (AC) | Oui |
| 9F27 | Données d'informations du cryptogramme (CID) | Oui |
| 9F33 | Capacités du terminal | - |
| 9F34 | Résultats de la méthode de vérification du titulaire de la carte (CVM) | Oui |
| 9F35 | Type de terminal | - |
| 9F36 | Compteur de transactions de l'application | Oui |
| 9F37 | Numéro imprévisible | Oui |
| 9F39 | Mode de saisie du point de service (POS) | - |
| 9F40 | Fonctionnalités supplémentaires du terminal | - |
| 9F41 | Compteur de séquence de transaction | - |
| 9F49 | Liste d'objets de données d'authentification de données dynamique (DDOL) | - |
| 9F53 | Code de catégorie de transaction | - |
| 9F5A | EMV (noyau 3) : identifiant du programme de l'application (ID du programme) EMV (noyau 4) : identifiant du produit de l'adhésion |
- |
| 9F5B | EMV (noyau 3) : résultats du script de l'émetteur EMV (noyau 2) : DSDOL EMV (noyau 4) : numéro d'adhésion du produit |
- |
| 9F66 | EMV (noyau 2) : PUNATC (piste 2) EMV (noyau 3) : qualificateurs de transaction du terminal (TTQ) |
- |
| 9F6E | Indicateur de facteur de formulaire | - |
| 9F7C | Données exclusives du client (CED) | - |
Si vous indiquez les balises EMV et les champs de demande d'API correspondants dans la demande de transaction, la passerelle utilise la valeur fournie dans le champ de demande d'API correspondant. Par exemple, si vous envoyez sourceOfFunds.provided.card.emvRequest.9F1C avec la valeur « Lane_03 » et posTerminal.lane avec la valeur « Lane_04 », posTerminal.lane avec la valeur « Lane_04 » est envoyé à l'acquéreur et retourné avec la réponse de la transaction. Cela peut être très utile si vous voulez remplacer les balises EMV et contrôler les valeurs suivant les champs. Veuillez noter qu'une utilisation de ce type est plutôt rare et ne doit donc être prise en compte que si votre intégration la requiert.
Balises EMV prises en charge et champs de demande d'API correspondants
Le tableau ci-dessous répertorie les balises EMV lorsque la passerelle renseigne les champs de demande d'API correspondants avec les valeurs fournies dans les balises EMV.
Balise EMV |
Nom de la balise EMV |
Champ de demande d'API correspondant |
|---|---|---|
| 56 | Piste 1 | sourceOfFunds.provided.card.track1 |
| 57 | Données équivalentes de la piste 2 | sourceOfFunds.provided.card.track2 |
| 5A | Numéro de séquence PAN (Application Primary Account) | sourceOfFunds.provided.card.number |
| 5F24 | Date d'expiration de l'application | sourceOfFunds.provided.card.expiry.year sourceOfFunds.provided.card.expiry.month |
| 5F34 | Numéro de séquence PAN | sourceOfFunds.provided.card.sequenceNumber |
| 9C | Avance de trésorerie | order.cashAdvance |
| 9F03 | Montant de remise | order.cashbackAmount |
| 9F1A | Code pays du terminal | posTerminal.address.country |
| 9F1C | Identification du terminal | posTerminal.lane |
| 9F1E | Numéro de série du périphérique d'interface | posTerminal.serialNumber |
| 9F33 | Capacités du terminal | posTerminal.inputCapability posTerminal.pinEntryCapability |
| 9F35 | Type de terminal | posTerminal.attended posTerminal.cardholderActivated |
La passerelle retourne le champ sourceOfFunds.provided.card.emvResponse dans la réponse Retrieve Order (Extraire la commande) et Retrieve Transaction (Extraire la transaction). Ce champ contient les données générées par l'émetteur, que la carte/l'appareil peut utiliser à des fins de vérification pour terminer ou refuser la transaction. Il peut également comporter des balises EMV supplémentaires de l'émetteur, notamment des balises répercutées par la demande.
Le tableau ci-dessous répertorie certaines des balises EMV pouvant être retournées par une réponse Authorization (Autorisation) en ligne.
| Balise EMV | Nom |
|---|---|
| 8A | Code de réponse de l'autorisation |
| 89 | Code d'autorisation |
| 91 | Données d'authentification de l'émetteur |
| 71 | Modèle de script de l'émetteur 1 |
| 72 | Modèle de script de l'émetteur 2 |
Le champ sourceOfFunds.provided.card.emvRequest fourni dans la demande est répercuté dans la réponse de laquelle les balises EMV identifiées comme étant sensibles PCI sont exclues.
Votre acquéreur peut demander à ce que des éléments de données EMV supplémentaires soient inclus lors de l'annulation d'une transaction EMV. Par exemple, la balise EMV DF01 (Résultats du script de l'émetteur) peut être requise. Veuillez contacter votre acquéreur pour connaître ses besoins spécifiques.
Traiter une transaction par bande magnétique
Si les données de piste de la carte sont lues à partir de la piste magnétique de la carte,
- Indiquez les données de la piste 1 dans le champ
sourceOfFunds.provided.card.track1ou les données de la piste 2 dans le champsourceOfFunds.provided.card.track2. Si les pistes 1 et 2 sont toutes deux disponibles sur le terminal, indiquez les deux balises dans la demande de transaction. - Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
sourceOfFunds.provided.card.track1 [REST][NVP]
sourceOfFunds.provided.card.track2 [REST][NVP]
Vous trouverez ci-dessous un exemple de transaction Authorization (Autorisation) en ligne à l'aide des données de bande magnétique.
| URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Méthode HTTP | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": 80,
"currency": "AUD"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "015",
"expiry": {
"year": "39",
"month": "01"
},
"track2": ";5123456789012346=17051019681143384001?",
"track1": "%B5123456789012346^MR JOHN R SMITH ^17051019681143300001 840 ?;"
}
}
},
"posTerminal": {
"lane": "AdamLane",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED",
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"location": "MERCHANT_TERMINAL_OFF_PREMISES"
}
}
{
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 80,
"creationTime": "2017-05-31T07:49:46.351Z",
"currency": "AUD",
"id": "sa-e229682a-2163-47cf-b080-fb60dd148192",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 80,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"lane": "AdamLane",
"location": "MERCHANT_TERMINAL_OFF_PREMISES",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"response": {
"acquirerCode": "00",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "015",
"trackDataProvided": true
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T07:49:46.351Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "SYSTEST_ACQ1",
"merchantId": "12345678"
},
"amount": 80,
"authorizationCode": "000001",
"currency": "AUD",
"frequency": "SINGLE",
"id": "1",
"receipt": "1705313",
"source": "CARD_PRESENT",
"terminal": "0006",
"type": "AUTHORIZATION"
},
"version": "43"
}
Traiter une transaction saisie
Si le numéro de carte a été saisi manuellement sur le clavier du terminal,
- Renseignez le numéro de carte saisi dans le champ de demande
sourceOfFunds.provided.card.number. - Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
sourceOfFunds.provided.card.number[REST][NVP]
Vous trouverez ci-dessous un exemple de transaction Authorization (Autorisation) en ligne en utilisant un numéro de carte saisi manuellement.
| URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Méthode HTTP | PUT |
{
"posTerminal": {
"serialNumber": "13130PP800781435",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"lane": "S2_Lane",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"attended": "ATTENDED",
"inputCapability": "KEY_ENTRY",
"location": "MERCHANT_TERMINAL_ON_PREMISES"
},
"apiOperation": "AUTHORIZE",
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "000",
"expiry": {
"year": "39",
"month": "01"
}
}
}
},
"order": {
"amount": "100.00",
"currency": "EUR"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 100,
"creationTime": "2017-05-31T08:59:47.194Z",
"currency": "EUR",
"id": "sa-529e784a-e11d-474d-8012-c0790531bb0f",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 100,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "ATTENDED",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "KEY_ENTRY",
"lane": "S2_Lane",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"serialNumber": "13130PP800781435"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "000"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T08:59:47.194Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 100,
"authorizationCode": "471223",
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "170531475",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "AUTHORIZATION"
},
"version": "43"
}
Traiter une transaction avec cryptage P2PE (Point-to-Point Encryption)
P2PE est une norme mise en place par le conseil de normalisation pour la sécurité des données de l'ICP (PCI Security Standards Council). Avec la norme P2PE, les données de carte sensibles sont cryptées sur le terminal immédiatement après leur lecture. Cela renforce la sécurité des transactions avec titulaire de la carte présent et réduit vos obligations en matière de conformité ICP, car vous n'avez pas à manipuler des données sensibles.
Pour traiter une transaction P2PE :
- Indiquez les données P2PE DUKPT du terminal dans les champs suivants :
sourceOfFunds.provided.card.p2pe.keySerialNumber: Vous devez fournir le numéro de série de la clé DUKPT fourni par le terminal.sourceOfFunds.provided.card.p2pe.payload: Si ce champ est renseigné,sourceOfFunds.provided.card.numbern'est pas obligatoire. La passerelle extrait toutes les informations appropriées de la carte à partir des données de paiement fournies.posTerminal.serialNumber:sourceOfFunds.provided.card.p2pe.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: Si vous ne renseignez pas ce champ, la passerelle prend par défaut la valeur deVALIDsourceOfFunds.provided.card.p2pe.initializationVector: Ce champ peut être ignoré si le terminal n'utilise pas de vecteur d'initialisation pour définir le cryptage.
- Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
Référence de l'API P2PE [REST][NVP]
Le tableau ci-dessous résume les contraintes de champ pour le groupe de paramètres sourceOfFunds.provided.card.p2pe.
| Si le champ | alors la passerelle... | ||
|---|---|---|---|
sourceOfFunds.provided.card.p2pe. initializationVector |
sourceOfFunds.provided.card.p2pe. keySerialNumber |
sourceOfFunds.provided.card.p2pe. payload | |
| est renseigné | est renseigné | n'est pas renseigné | rejette la demande de transaction. |
| est renseigné | est renseigné mais en texte clair avant ou après le décryptage | est renseigné | retourne une erreur et une entrée est générée dans le journal de sécurité. |
Réponse de transaction
Le champ sourceOfFunds.provided.card.encryption retourne DUKPT (de la version 43 de DirectAPI et versions ultérieures) dans la réponse de la transaction afin d'indiquer que les données de carte ont été cryptées. Les champs du groupe de paramètres sourceOfFunds.provided.card.p2pe ne sont pas retournés dans la réponse.
Intégration en vue d'utiliser le PIN en ligne
Le code PIN entré par le titulaire de la carte est crypté à la source, sur l'appareil utilisé pour la saisie du code PIN. Mastercard Gateway prend en charge les données de code PIN en ligne cryptées par DUKPT (Derived Unique Key Per Transaction) dans la version 45 de DirectAPI et versions ultérieures.
- Indiquez les données PIN cryptées par DUKPT du terminal dans les champs suivants :
sourceOfFunds.provided.card.pin.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
Intégration en vue d'utiliser mPOS
La passerelle prend en charge l'acceptation des paiements sur les appareils POS mobiles (mPOS) à partir de l'API version 56 et versions ultérieures. Pour activer cette fonctionnalité, indiquez les éléments suivants dans la transaction Verify (Vérifier), Authorize (Autoriser), Capture (Collecter), Pay (Payer) ou Refund (Rembourser) :
posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE- Indiquez la valeur du lecteur de carte dans le champ
posTerminal.mobile.cardInputDevice
.BUILT_IN: téléphone mobile ou tablette standard avec uniquement un lecteur sans contact intégré. Dans ce cas, le champ posTerminal.pinEntryCapability doit être défini sur SOFTWARE_ONLINE_PIN_ONLY, sinon la passerelle rejette la transaction.INTEGRATED_DONGLE: terminal mobile dédié avec lecteur de carte intégré. Dans ce cas, le champ posTerminal.pinEntryCapability doit être défini sur PIN_SUPPORTED or OFFLINE_PIN_ONLY, sinon la passerelle rejette la transaction.SEPARATE_DONGLE: appareil standard ou terminal mobile dédié, avec lecteur de carte séparé. Dans ce cas, le champ posTerminal.pinEntryCapability doit être défini sur PIN_SUPPORTED or OFFLINE_PIN_ONLY, sinon la passerelle rejette la transaction.
- Renseignez les champs obligatoires.
- Si requis, renseignez les champs facultatifs.
Réponse de transaction
L'authentification par code PIN peut échouer si le payeur entre un code PIN non valide, dépasse le nombre autorisé de tentatives de saisie du code PIN ou ignore la saisie du code PIN lorsque celui-ci est requis pour terminer la transaction.
Dans ces cas où l'autorisation échoue en raison d'une erreur d'authentification par code PIN, la passerelle retourne des codes de réponse d'autorisation spécifiques. Vous pouvez réutiliser le même ID de commande sur la transaction suivante.
Test de l'intégration du titulaire de la carte présent
Vous pouvez tester votre intégration en utilisant des cartes de test spécifiques à votre acquéreur.