- Directives d'intégration
- Fonctionnalités prises en charge (Opérations de paiement)
- Prise en charge de l'agrégateur
Prise en charge de l'agrégateur
Mastercard Gateway propose une prise en charge vous permettant d'agir en tant qu'agrégateur. Cette fonctionnalité vous permet de proposer des services en ligne pour accepter les paiements électroniques pour le compte d'autres commerçants (appelés sous-commerçants), aucune relation contractuelle avec l'acquéreur ni avec la passerelle n'étant requise pour le sous-commerçant. Il s'agit d'une option très intéressante pour les commerçants ayant peu de transactions qui leur permet d'accepter des paiements en ligne de la part de leurs payeurs et d'être très rapidement configurés.
Le sous-commerçant ne doit avoir qu'une entente contractuelle avec vous, l'agrégateur. Vous gérez la relation contractuelle avec l'acquéreur, recevez les fonds pour le compte du sous-commerçant et réglez ces fonds au sous-commerçant.
- La fonctionnalité d'agrégateur est prise en charge par API version 32 et ultérieure.
- Si vous voulez agir en tant qu'agrégateur, vous devez satisfaire certaines exigences des systèmes de cartes. Pour plus d'informations, veuillez contacter votre acquéreur et/ou les systèmes de cartes.
- American Express requiert l'adresse électronique et le numéro de téléphone de l'agrégateur de paiement, ainsi que les autres détails du sous-commerçant.
Conditions préalables
Vous devez contacter votre acquéreur, qui vous inscrira auprès des systèmes de cartes afin de vous définir comme agrégateur. Votre acquéreur peut vous délivrer un ID et/ou un nom d'agrégateur. Donnez ces détails à votre your payment service provider.
Votre Your payment service provider doit configurer en conséquence votre profil de commerçant (lien acquéreur-commerçant) sur la passerelle.
Soumission de transactions API pour le compte de sous-commerçants
Lors de la soumission d'une transaction pour le compte d'un sous-commerçant à l'aide des opérations API suivantes, vous devez spécifier les détails du sous-commerçant indiqués ci-dessous dans le groupe de paramètres order.subMerchant.
Demandes API :
PAYAUTHORIZE- Standalone
CAPTURE(Collecte autonome) - Standalone
REFUND(Remboursement autonome) VERIFYUPDATE_SESSION
Détails du sous-commerçant :
order.subMerchant.identifier(obligatoire siorder.subMerchant.tradingNameest fourni)order.subMerchant.registeredNameorder.subMerchant.tradingName(obligatoire siorder.subMerchant.identifierest fourni)order.subMerchant.bankIndustryCode- Champs
order.subMerchant.address.* order.subMerchant.phoneorder.subMerchant.email
Si indiqués, ces paramètres seront retournés dans les réponses suivantes :
RETRIEVE_TRANSACTIONRETRIEVE_ORDERRETRIEVE_SESSION
Si la passerelle ne prend pas en charge les agrégateurs pour votre acquéreur, une demande comportant des détails de sous-commerçant sera rejetée.
Les détails du sous-commerçant s'appliquent à toutes les transactions dans une commande. Ils ne peuvent être indiqués que sur les transactions initiales, c.-à-d. les transactions de création d'une commande. S'ils sont indiqués sur les transactions ultérieures (c.-à-d. les transactions pour une commande existante, telles qu'une demande de type CAPTURE (Collecter) ou REFUND (Rembourser) ultérieure), la passerelle rejette la demande.
Tokenization
Pour les versions de l'API inférieures à 70, si vous agissez en tant qu'agrégateur, vous ne pouvez pas utiliser la fonctionnalité de Tokenization. La passerelle rejette les demandes de transaction comportant des détails de sous-commerçant pour les commerçants pour lesquels la fonctionnalité de Tokenization est activée.
A compter de la version 70 de l'API, si vous agissez en tant qu'agrégateur, vous pouvez utiliser la fonctionnalité de Tokenization. La prise en charge de la fonctionnalité de Tokenization est ajoutée aux opérations suivantes :
Demande :
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
DELETE_TOKENSEARCH_TOKEN, andRETRIEVE_TOKEN.
Réponse :
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
TOKENIZE_BROWSER_PAYMENT, andRETRIEVE_TOKEN.
En tant qu'agrégateur utilisant la fonctionnalité de Tokenization, vous devez fournir les détails suivants du sous-commerçant dans le groupe de paramètres subMerchant :
subMerchantsubMerchant.identifier
En tant que commerçant agrégateur, vous devez
- fournir l'identifiant du sous-commerçant dans toutes les opérations de segmentation en jetons
- fournir les détails du sous-commerçant dans les demandes de transaction
- être activé en tant qu'agrégateur, et
- utiliser un lien d'acquéreur qui prend en charge les transactions d'agrégateur (la capacité de prise en charge d'agrégateur doit être activée dans le lien d'acquéreur).
Limites
Les fonctionnalités suivantes ne sont actuellement pas disponibles :
- Un agrégateur ne peut pas être configuré avec un référentiel avec Stratégie de génération de jeton = Acquéreur.
- Un agrégateur ne peut pas être configuré avec un référentiel de jetons externe (tokenprovider = LTV ou TV2G).
- Un agrégateur ne peut pas être configuré avec la segmentation en jetons de réseau pour les jetons de passerelle.
Hosted Checkout
Si vous voulez proposer la fonctionnalité Hosted Checkout à vos sous-commerçants, vous devez leur fournir une interface vers votre intégration avec Hosted Checkout.
Si vous indiquez des détails de sous-commerçant, vous devez indiquer un ID de session lors de l'appel de Checkout.configure(). Soumettez une demande APICREATE_CHECKOUT_SESSION et incluez les détails de la commande du sous-commerçant pour générer un ID de session. Les navigateurs du payeur reviennent sur votre application et vous devez rediriger le payer vers l'application du commerçant.
Utilisez Checkout.configure() pour fournir les détails d'affichage du sous-commerçant, tels que le nom, l'adresse, les coordonnées et le logo du commerçant. Ces détails sont présentés au payeur lors de l'interaction Hosted Checkout.
Authentification 3-D Secure EMV
Pour permettre aux sous-commerçants d'utiliser l'authentification 3-D Secure EMV (3DS2) via la passerelle, les agrégateurs doivent soumettre les détails appropriés du sous-commerçant dans la demande Initiate Authentication. Lorsque les détails du sous-commerçant sont soumis à la passerelle, celle-ci utilise ces détails à la place des détails de l'agrégateur dans le message d'authentification en aval. Les champs à renseigner varient selon les systèmes. Les systèmes pris en charge sont notamment :
- Mastercard SecureCode™
- Verified by Visa
- American Express SafeKey
- MADA secure
Si l'authentification est suivie d'un paiement utilisant une opération Authorize (Autoriser) ou Pay (Payer) faisant référence à l'ID d'authentification 3DS2, les détails du sous-commerçant fournis dans la demande Initiate Authentication sont également utilisés dans les opérations Authorize (Autoriser)/Pay (Payer).
Étape 1 : Initier l'authentification
Fournissez les détails suivants sur la demande Initiate Authentication (Initier l'authentification) pour votre sous-commerçant en plus des autres champs obligatoires répertoriés dans la rubrique Initier l'authentification du Guide d'intégration.
Pour voir les champs de réponse clés pour la réponse Initiate Authentication (Initier l'authentification), reportez-vous à la rubrique Initier l'authentification dans le Guide d'intégration.
Détails du sous-commerçant
order.subMerchant.identifier(obligatoire pour tous les systèmes 3DS2 pris en charge)order.subMerchant.tradingName(obligatoire pour tous les systèmes 3DS2 pris en charge)order.subMerchant.bankIndustryCode(obligatoire pour tous les systèmes 3DS2 pris en charge)order.subMerchant.registeredNameorder.subMerchant.address.country(obligatoire pour tous les systèmes 3DS2 pris en charge)order.subMerchant.address.*(autres champs d'adresse)order.subMerchant.phoneorder.subMerchant.email
Détails 3DS2
Fournissez les détails de configuration 3DS2 suivants à votre sous-commerçant. Vous devez au préalable être activé pour le système d'authentification 3DS2 correspondant sur votre profil de commerçant pour lequel le sous-commerçant peut effectuer des authentifications de payeur 3DS2.
order.subMerchant.websiteUrl: URL du site Web du sous-commerçant. Si elle n'est pas indiquée, l'URL du site Web de votre profil de commerçant sera utilisée.order.subMerchant.authentication[n].protocolorder.subMerchant.authentication[n].3DS2.requestorIdorder.subMerchant.authentication[n].3DS2.requestorName
Pour Mastercard SecureCode, JCB J/Secure et MADA secure, ne fournissez pas de détails de l'authentification. L'ID et le nom du demandeur sont générés par la passerelle.
Pour Verified by Visa, dans les détails de l'authentification, indiquez uniquement le protocole d'authentification. L'ID et le nom du demandeur sont générés par la passerelle.
Pour American Express Safekey, la passerelle utilisera l'ID de demandeur « AGG », qui signifie agrégateur. Si American Express le demande, vous pouvez le remplacer et en utiliser un autre. La passerelle, comme les autres systèmes, créera le nom du demandeur.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Méthode HTTP | PUT |
{
"authentication": {
"acceptVersions":"3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order": {
"currency": "USD",
"subMerchant": {
"authentication":[
{
"protocol":"AMEX_SAFEKEY",
"3DS2":{
"requestorId":"testRequestorId",
"requestorName":"testRequestorName"
}
}
],
"identifier": "123456",
"tradingName": "SubmerchantName",
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"registeredName": "SubmerchantRegisteredName"
}
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174"
}
}
},
"apiOperation": "INITIATE_AUTHENTICATION"
}
{
"authentication":
{
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"acceptVersions": "3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customized": {
"3DS": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==",
"methodUrl": "https://qa06.gateway.mastercard.com/acs/mastercard/v2/method"
}
}
},
"redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\"> </iframe> <form id=\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==\"/> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TESTMITSUKO_GWS",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:21:19.966Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:21:19.966Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
Étape 2 : Authentifier le payeur
Pour toutes les instructions relatives au flux de sous-commerçant, reportez-vous à la rubrique Authentifier le payeur.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Méthode HTTP | PUT |
{
"correlationId": "foo",
"order": {
"amount": "100",
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month" : "01",
"year" : "39"
}
}
}
},
"device": {
"browser": "MOZILLA",
"browserDetails": {
"3DSecureChallengeWindowSize": "FULL_SCREEN",
"acceptHeaders": "application/json",
"colorDepth": 24,
"javaEnabled": true,
"language": "en-US",
"screenHeight": 640,
"screenWidth": 480,
"timeZone": 273
},
"ipAddress": "127.0.0.1"
},
"apiOperation": "AUTHENTICATE_PAYER"
}
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"3dsServerTransactionId": "fc0f4848-7343-4300-986a-96d0ba403485",
"acsTransactionId": "ebd1628f-b62a-44f6-bb2d-480359ac3e70",
"directoryServerId": "A999999999",
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName",
"transactionStatus": "Y"
},
"payerInteraction": "NOT_REQUIRED",
"redirect": {
"customized": {
"3DS": {
"acsUrl": "https://qa06.gateway.mastercard.com/callbackInterface/gateway/3a672661a6b7027834df3e5863e78f02152c7b99b18b0f9ea8bbd30f86323dc2",
"cReq": "e30="
}
},
"domainName": "qa06.gateway.mastercard.com"
},
"redirectHtml":"<div id=\"threedsFrictionLessRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"challengeFrame\" name=\"challengeFrame\" </iframe> <form id=\"threedsFrictionLessRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"order.id\" value=\"TEST1234\"/> <input type=\"hidden\" name=\"transaction.id\" value=\"123\"/> input type=\"hidden\" name=\"response.gatewayRecommendation\" value=\"PROCEED\"/> <input type=\"hidden\" name=\"result\" value=\"SUCCESS\"/> </form> <script id=\"authenticate-payer-script\"> </script> var e=document.getElementById(\"threedsFrictionLessRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "foo",
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:25:30.340Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:25:30.340Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"acquirer": {
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
Étape 3 : Utiliser les résultats de l'authentification dans une opération de paiement
Pour toutes les instructions relatives au flux de sous-commerçant, reportez-vous à la rubrique Utiliser les résultats de l'authentification dans une opération de paiement.
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Méthode HTTP | PUT |
{
"apiOperation": "AUTHORIZE",
"authentication": {
"transactionId": "123"
},
"order": {
"amount": "100",
"currency": "USD",
"reference": "300"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month": "01",
"year": "39"
}
}
},
"type": "CARD"
},
"transaction": {
"source": "INTERNET",
"reference": "3600"
}
}
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"protocolVersion": "2.1.0",
"transactionStatus": "Y"
},
"transactionId": "123",
"version": "3DS2"
},
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2022-03-03T02:21:19.948Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:45:56.851Z",
"merchantAmount": 100.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "USD",
"reference": "300",
"status": "AUTHORIZED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 100.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "000",
"acquirerMessage": "Approved ",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:45:56.851Z",
"timeOfRecord": "2022-03-03T02:45:56.762Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "AMEXGWS",
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"authorizationCode": "007257",
"currency": "USD",
"id": "1234",
"receipt": "2203031",
"reference": "3600",
"source": "INTERNET",
"stan": "1",
"terminal": "123456",
"type": "AUTHORIZATION"
},
"version": "64"
}