- 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 webServices Integration 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 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://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://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 webServices Integration 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. ARC Pay 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 webServices Integration 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.