The Mastercard Payment Gateway offers support for you to act as an aggregator. This enables you to offer online services for accepting electronic payments to other merchants (called sub-merchants) where the sub-merchant is not required to have a contractual relationship neither with the acquirer nor with the gateway. This is an attractive option for merchants with small numbers of transactions to accept online payments from their payers and get set up very quickly.
The sub-merchant only needs a contractual agreement with you, the aggregator. You manage the contractual relationship with the acquirer, receive the sub-merchant funds and settle these on towards the sub-merchant.
You must contact your acquirer, who will sign you up with the card schemes for the purpose of setting you up as an aggregator. Your acquirer might issue you with an aggregator ID and/or name. Provide these details to your payment service provider.
Your payment service provider must set up your merchant profile (merchant acquirer link) in the gateway accordingly.
When submitting a transaction for a sub-merchant via the following API operations, you may provide the sub-merchant details indicated below in the order.subMerchant parameter group.
API Requests:
PAYAUTHORIZECAPTUREREFUNDVERIFYUPDATE_SESSIONSub-Merchant Details:
order.subMerchant.identifier (mandatory if order.subMerchant.tradingName is provided)order.subMerchant.registeredNameorder.subMerchant.tradingName (mandatory if order.subMerchant.identifier is provided)order.subMerchant.bankIndustryCodeorder.subMerchant.address.* fieldsorder.subMerchant.phoneorder.subMerchant.emailIf provided, these will be returned in the following responses:
RETRIEVE_TRANSACTIONRETRIEVE_ORDERRETRIEVE_SESSIONIf the gateway does not provide support for aggregators for your acquirer, a request with sub-merchant details will be rejected.
The sub-merchant details apply to all transactions in an order. They can only be provided on initial transactions, i.e. transactions that create an order. If provided on subsequent transactions (that is, transactions for an existing order, like a subsequent CAPTURE or REFUND request), the gateway rejects the request.
For API versions lower than 70, if you are acting as an aggregator you may not use the Tokenization functionality. The gateway rejects transaction requests with sub-merchant details for merchants that are enabled for Tokenization.
From the API version 70 onwards, if you are acting as an aggregator, you can use the Tokenization functionality. The support for Tokenization functionality is added to the following operations:
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)DELETE_TOKENSEARCH_TOKEN, andRETRIEVE_TOKEN.TOKENIZECreate or Update TokenCreate or Update Token (system generated token)TOKENIZE_BROWSER_PAYMENT, andRETRIEVE_TOKEN.As an Aggregator using Tokenization functionality, you must provide the following sub-merchant details in the subMerchant parameter group.
subMerchant
subMerchant.identifierAs an aggregator merchant you are expected to
The following functionalities are currently not available:
If you want to provide your sub-merchants with Hosted Checkout functionality you must provide them with an interface to your integration with Hosted Checkout.
If you provide sub-merchant details you must provide a session ID when calling Checkout.configure(). Submit an APICREATE_CHECKOUT_SESSION request and include the submerchant order details to generate a session ID. The payer’s browser will be returned to your application and you must redirect the payer to the sub-merchant’s application.
Use Checkout.configure() to provide the sub-merchant display details, such as merchant name, address, contact details, and logo. These details are presented to the payer during the Hosted Checkout interaction.
To enable sub-merchants to use EMV 3-D Secure authentication (3DS2) via the gateway, aggregators must submit the relevant sub-merchant details in the Initiate Authentication request. When sub-merchant details are submitted to the gateway, the gateway uses the sub-merchant details in place of the aggregator details in the downstream authentication message. The fields that need to be provided vary by scheme. Supported schemes include:
If the authentication is followed by a payment using an Authorize or Pay operation that references the 3DS2 authentication ID, then the sub-merchant details provided in the Initiate Authentication request are also used in the Authorize/Pay operations.
Provide the following details on the Initiate Authentication request for your sub-merchant in addition to other required fields as listed in the Initiate Authentication section in the Integration Guide.
To see key response fields for the Initiate Authentication response, refer to the Initiate Authentication section in the Integration Guide.
order.subMerchant.identifier (mandatory for all supported 3DS2 schemes)order.subMerchant.tradingName (mandatory for all supported 3DS2 schemes)order.subMerchant.bankIndustryCode (mandatory for all supported 3DS2 schemes)order.subMerchant.registeredNameorder.subMerchant.address.country (mandatory for all supported 3DS2 schemes)order.subMerchant.address.* (other address fields)order.subMerchant.phoneorder.subMerchant.emailProvide the following 3DS2 configuration details for your sub-merchant. As a prerequisite, you must be enabled for the respective 3DS2 authentication scheme on your merchant profile for which the sub-merchant can perform 3DS2 payer authentications.
order.subMerchant.websiteUrl: The sub-merchant's website URL. If not provided, the website URL from your merchant profile will be used. order.subMerchant.authentication[n].protocol order.subMerchant.authentication[n].3DS2.requestorIdorder.subMerchant.authentication[n].3DS2.requestorNameFor MasterCard SecureCode, do not provide authentication details. The Requestor ID and Requestor Name are generated by the gateway.
For Verified by Visa in the authentication details, only provide the authentication protocol. The Requestor ID and Requestor Name are generated by the gateway.
For American Express Safekey, the gateway will use the Requestor ID 'AGG', which stands for Aggregator. If American Express requests it, you can override this and use a different one. The gateway, like other schemes, will create the Requestor Name.
| URL | https://ap.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | 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"
}
Refer to Authenticate Payer for all instructions related to sub-merchants flow.
| URL | https://ap.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | 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"
}
Refer to Use the Authentication Result in a Payment Operation for all instructions related to sub-merchant's flow.
| URL | https://ap.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | 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"
}
Copyright © 2023 Mastercard