Aggregator
Your payment service provider allows you to act as an aggregator, enabling you to offer online services for accepting electronic payments to other merchants (called sub-merchants). Becoming a sub-merchant can be an attractive option for merchants who only need to handle a small number of transactions and want to set up very quickly.
The sub-merchant is not required to have a contractual relationship with the acquirer or the gateway. They only need 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 from API v32 onwards.
- Card schemes have certain requirements that you need to comply with if you want to act as an aggregator. For details, contact your acquirer.
- The WS-API requests for AMEX requires the email and telephone number of the payment aggregator in addition to the sub-merchant details.
Supported for following methods:
| Integration methods | Payment methods | Operations* |
|---|---|---|
| All except alternative payment methods (APM) |
* Where sub-merchant details are included. |
Prerequisites
To become an aggregator:
- Contact your acquirer and ask them to sign you up with the card schemes for the purpose of setting you up as an aggregator. Your acquirer may issue you an aggregator ID and name. Provide these details to your Payment Service Provider (PSP).
- Request your PSP to enable you as an aggregator, that is set up the merchant acquirer link in your merchant profile in the gateway.
Submitting transactions for sub-merchants
You can submit the following transaction operations on behalf of your sub-merchants:
- PAY
- AUTHORIZE
- STANDALONE CAPTURE
- STANDALONE REFUND
- VERIFY
- INITIATE CHECKOUT
- UPDATE SESSION
When submitting the transaction, provide the following sub-merchant details in the order.subMerchant object of the request:
order.subMerchant.identifier(mandatory iforder.subMerchant.tradingNameis provided)order.subMerchant.registeredNameorder.subMerchant.tradingName(mandatory iforder.subMerchant.identifieris provided)order.subMerchant.bankIndustryCodeorder.subMerchant.address.cityorder.subMerchant.address.countryorder.subMerchant.phoneorder.subMerchant.email
If the gateway does not support aggregators for your acquirer, a request with sub-merchant details is rejected.
The sub-merchant details apply to all transactions in an order, but they can only be provided on initial transactions that create an order. If provided on subsequent transactions such as transactions for an existing order like a subsequent CAPTURE or REFUND request, the gateway rejects the request. If the sub-merchant details have been provided, those details are returned when you retrieve the details of a related transaction, order, or session with the applicable retrieval operation.
To view an example of an API request with aggregator data, download the Postman collection.
Sharing Hosted Checkout
If you want to provide your sub-merchants the Hosted Checkout functionality, you must provide them an interface to your Hosted Checkout integration.
To share your Hosted Checkout with your sub-merchants (from the API v64 onwards):
- Submit an INITIATE CHECKOUT request and include the sub-merchant order details in it. The response returns a session ID.
- Provide the session ID when calling the
Checkout.configure()function. Use the function 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. - When the payer's browser is returned to your app, redirect the payer to the sub-merchant's app.
Enabling 3D Secure authentication
To enable your sub-merchants to use 3D Secure (3DS) authentication through the gateway, you must submit the relevant sub-merchant details in the INITIATE AUTHENTICATION request. When sub-merchant details are submitted, the gateway uses them instead of the aggregator details in the downstream authentication message. The fields that need to be provided vary by scheme.
The supported schemes include:
- Mastercard® SecureCode™
- Verified by Visa
- American Express SafeKey
If the authentication is followed by a payment using an AUTHORIZE or PAY transaction that references the 3DS authentication ID, the gateway uses the sub-merchant details provided in the INITIATE AUTHENTICATION request automatically when processing the AUTHORIZE or PAY transaction, and you do not need to repeat those details in your transaction request.
Prerequisites
On your merchant profile, you must be enabled for the 3DS authentication scheme that the sub-merchant wants to use to perform 3DS payer authentications.
Step 1: Initiate Authentication
Create the INITIATE AUTHENTICATION request, following the general instructions (for Payer Authentication or JavaScript API implementation).
Add the following details to the request:
- 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.registeredNameorder.subMerchant.address.country(mandatory for all supported 3DS2 schemes)order.subMerchant.address.* (other address fields)order.subMerchant.phoneorder.subMerchant.email
- Sub-merchant's 3DS configuration details:
order.subMerchant.websiteUrl(sub-merchant's web site URL; if not provided, the web site URL from your merchant profile is used)order.subMerchant.authentication[n].protocolorder.subMerchant.authentication[n].3DS2.requestorIdorder.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 uses the Requestor ID 'AGG', which stands for Aggregator. If American Express requests it, you can override this and use a different one. The gateway generates the Requestor Name.
INITIATE AUTHENTICATION request example
| URL | https://{{host}}/api/rest/version/llaatteesstt/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 |
| HTTP Method | PUT |
| Click here to download Postman Collection - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/1. INITIATE AUTHENTICATION | |
{
"apiOperation":"INITIATE_AUTHENTICATION",
"authentication":{
"acceptVersions":"3DS2",
"channel":"PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order":{
"currency":"{{currency}}",
"subMerchant": {
"authentication":[
{
"protocol":"AMEX_SAFEKEY",
"3DS2":{
"requestorId":"testRequestorId",
"requestorName":"testRequestorName"
}
}
],
"websiteUrl": "http://www.yoursite.com",
"identifier": "123456",
"tradingName": "SubmerchantName",
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"registeredName": "SubmerchantRegisteredName"
}
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"{{fpan}}"
}
}
}
}
INITIATE AUTHENTICATION response example
{
"authentication":
{
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.2.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
The AUTHENTICATE PAYER request is identical for aggregators and non-aggregators. Follow the general instructions (for Payer Authentication or JavaScript API implementation).
AUTHENTICATE PAYER request example
| URL | https://{{host}}/api/rest/version/llaatteesstt/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 |
| HTTP Method | PUT |
| Click here to download Postman Collection - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/4. AUTHENTICATE PAYER | |
{
"sourceOfFunds": {
"provided": {
"card": {
"number": "{{fpan}}",
"expiry": {
"month": "{{expMonth}}",
"year": "{{expYear}}"
}
}
}
},
"correlationId": "foo",
"order": {
"amount": "10",
"currency": "{{currency}}"
},
"authentication": {
"redirectResponseUrl": "https://{{host}}/api/documentation/integrationGuidelines/index.html"
},
"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 example - 3DS 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.2.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 in a payment
The authentication result is used in a payment operation identically for aggregators and non-aggregators. Follow the general instructions (for Payer Authentication or JavaScript API implementation).
AUTHORIZE request example
| URL | https://{{host}}/api/rest/version/llaatteesstt/merchant/{{merchantId}}/order/{{orderId}}/transaction/2 |
| HTTP Method | PUT |
| Click here to download Postman Collection - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/6. AUTHORIZE | |
{
"apiOperation": "AUTHORIZE",
"authentication": {
"transactionId": "1"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "{{fpan}}",
"expiry": {
"month": "{{expMonth}}",
"year": "{{expYear}}"
},
"securityCode": "{{securityCode}}"
}
},
"type": "CARD"
},
"order": {
"currency": "{{currency}}",
"amount": "100.00"
},
"transaction": {
"source": "INTERNET"
}
}
AUTHORIZE response example
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"protocolVersion": "2.2.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"
}