Aggregator Support

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.

  • Aggregator functionality is supported by API version 32 and above.
  • Card schemes have certain requirements that you need to comply with if you want to act as an aggregator. For details, please contact your acquirer and/or the card schemes.
  • American Express requires the email and telephone number of the payment aggregator apart from other sub-merchant details.

Prerequisites

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.

Submitting API Transactions for Sub-Merchants

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:

  • PAY
  • AUTHORIZE
  • Standalone CAPTURE
  • Standalone REFUND
  • VERIFY
  • UPDATE_SESSION

Sub-Merchant Details:

  • order.subMerchant.identifier (mandatory if order.subMerchant.tradingName is provided)
  • order.subMerchant.registeredName
  • order.subMerchant.tradingName (mandatory if order.subMerchant.identifier is provided)
  • order.subMerchant.bankIndustryCode
  • order.subMerchant.address.* fields
  • order.subMerchant.phone
  • order.subMerchant.email

If provided, these will be returned in the following responses:

  • RETRIEVE_TRANSACTION
  • RETRIEVE_ORDER
  • RETRIEVE_SESSION

If 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.

Tokenization

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:

Request:

  • TOKENIZE
    • Create or Update Token
    • Create or Update Token (system generated token)
  • DELETE_TOKEN
  • SEARCH_TOKEN, and
  • RETRIEVE_TOKEN.

Response:

  • TOKENIZE
    • Create or Update Token
    • Create or Update Token (system generated token)
  • TOKENIZE_BROWSER_PAYMENT, and
  • RETRIEVE_TOKEN.

As an Aggregator using Tokenization functionality, you must provide the following sub-merchant details in the subMerchant parameter group.

  • subMerchant
    • subMerchant.identifier

As an aggregator merchant you are expected to

  • provide the sub-merchant identifier in all tokenization operations
  • provide sub-merchant details in the Transaction Requests
  • be enabled as an Aggregator, and
  • use an acquirer link that supports aggregator transactions (aggregatorsupport capability must be enabled in the acquiring link).

Limitations

The following functionalities are currently not available:

  • An aggregator cannot be configured with a repository with the Token Generation Strategy = Acquirer.
  • An aggregator cannot be configured with an external token repository (tokenprovider = LTV or TV2G).
  • An aggregator cannot be configured with the network tokenization for gateway tokens.

Hosted Checkout

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.

Do not provide sub-merchants with your gateway credentials. This would enable them to access transactions of your other sub-merchants.

EMV 3-D Secure Authentication

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:

  • MasterCard® SecureCode™
  • Verified by Visa
  • American Express SafeKey
Check with your payment service provider to see which scheme they support.

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.

Step 1: Initiate Authentication

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.

Sub-Merchant Details

  • 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.registeredName
  • order.subMerchant.address.country (mandatory for all supported 3DS2 schemes)
  • order.subMerchant.address.* (other address fields)
  • order.subMerchant.phone
  • order.subMerchant.email

3DS2 Details

Provide 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.requestorId
  • order.subMerchant.authentication[n].3DS2.requestorName

For 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.

Examples
Initiate Authentication Request
URL https://evopaymentsmexico.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"
	}
Initiate Authentication Response
	{
	"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"
}

Step 2: Authenticate Payer

Refer to Authenticate Payer for all instructions related to sub-merchants flow.

Examples
Authenticate Payer Request
URL https://evopaymentsmexico.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"
	}
Authenticate Payer Response - 3DS2 Frictionless Success
	{
		"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"
	}

Step 3: Use the Authentication Result in a Payment Operation

Refer to Use the Authentication Result in a Payment Operation for all instructions related to sub-merchant's flow.

Examples
Authorize Request
URL https://evopaymentsmexico.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"
		}
	}
Authorize Response
	{
		"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