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.tradingName
is provided)order.subMerchant.registeredName
order.subMerchant.tradingName
(mandatory iforder.subMerchant.identifier
is provided)order.subMerchant.bankIndustryCode
order.subMerchant.address.city
order.subMerchant.address.country
order.subMerchant.phone
order.subMerchant.disputeContactPhone
order.subMerchant.marketplaceId
order.subMerchant.governmentCountryCode
Theorder.subMerchant.marketplaceId
andorder.subMerchant.governmentCountryCode
are available from the v85 onwards.
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.registeredName
order.subMerchant.address.country
(mandatory for all supported 3DS2 schemes)order.subMerchant.address.
* (other address fields)order.subMerchant.phone
order.subMerchant.email
order.subMerchant.disputeContactPhone
order.subMerchant.marketplaceId
order.subMerchant.governmentCountryCode
Theorder.subMerchant.marketplaceId
andorder.subMerchant.governmentCountryCode
are available from the v85 onwards.
- 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].protocol
order.subMerchant.authentication[n].3DS2.requestorId
order.subMerchant.authentication[n].3DS2.requestorName
- For American Express Safekey, the gateway will use the 3DS 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.
INITIATE AUTHENTICATION request example
URL | https://{{host}}/api/rest/version/llaatteesstt/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 |
HTTP Method | PUT |
{ "apiOperation": "INITIATE_AUTHENTICATION", "authentication": { "acceptVersions": "3DS2", "channel": "PAYER_BROWSER", "purpose": "PAYMENT_TRANSACTION" }, "order": { "currency": "USD", "subMerchant": { "identifier": "828680860811", "tradingName": "Visa MP1", "address": { "city": "Pune", "company": "Pune", "country": "IND", "postcodeZip": "411047", "stateProvince": "Pun", "street": "Pune", "street2": "Pune" }, "bankIndustryCode": "1324", "email": "test@noreply.com", "websiteUrl": "https://test@noreply.com", "phone": "00000000", "disputeContactPhone": "+91 00000000", "registeredName": "MPGS", "marketplaceId": "AMAZONMAR!!", "governmentCountryCode": "IND" } }, "sourceOfFunds": { "provided": { "card": { "number": "5433570000000016" } } } }
INITIATE AUTHENTICATION response example
{ "authentication": { "3ds2": { "authenticationScheme": "MASTERCARD", "directoryServerId": "A000000004", "methodSupported": "NOT_SUPPORTED", "protocolVersion": "2.2.0", "requestorId": "MAS00001_INT_MPGS_DLD33102UQ18DHW2V", "requestorName": "Visa MP1" }, "acceptVersions": "3DS2", "channel": "PAYER_BROWSER", "purpose": "PAYMENT_TRANSACTION", "redirect": { "html": "<script id=\"initiate-authentication-script\"></script>" }, "version": "3DS2" }, "merchant": "D3S2_SOMB", "order": { "authenticationStatus": "AUTHENTICATION_AVAILABLE", "creationTime": "2024-07-16T16:14:03.181Z", "currency": "USD", "id": "NMC_608216124", "lastUpdatedTime": "2024-07-16T16:14:03.131Z", "merchantCategoryCode": "1324", "status": "AUTHENTICATION_INITIATED", "subMerchant": { "address": { "city": "Pune", "company": "Pune", "country": "IND", "postcodeZip": "411047", "stateProvince": "Pun", "street": "Pune", "street2": "Pune" }, "bankIndustryCode": "1324", "disputeContactPhone": "+91 00000000", "email": "test@noreply.com", "identifier": "828680860811", "phone": "00000000", "registeredName": "MPGS", "tradingName": "Visa MP1", "websiteUrl": "https://test@noreply.com", "marketplaceId": "AMAZONMAR!!", "governmentCountryCode": "IND" }, "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalRefundedAmount": 0 }, "response": { "gatewayCode": "AUTHENTICATION_IN_PROGRESS", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "fundingMethod": "DEBIT", "number": "543357xxxxxx0016", "scheme": "MASTERCARD" } }, "type": "CARD" }, "timeOfLastUpdate": "2024-07-16T16:14:03.131Z", "timeOfRecord": "2024-07-16T16:14:03.181Z", "transaction": { "amount": 0, "authenticationStatus": "AUTHENTICATION_AVAILABLE", "currency": "USD", "id": "1", "type": "AUTHENTICATION" }, "version": "85" }
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 |
{ "apiOperation": "AUTHENTICATE_PAYER", "authentication": { "redirectResponseUrl": "<host>/merchantSimulator/jsp/simple/output.jsp" }, "order": { "currency": "USD", "amount": 101.00 }, "sourceOfFunds": { "provided": { "card": { "number": "5433570000000016", "expiry": { "month": 1, "year": 39 } } } }, "device": { "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36", "browserDetails": { "3DSecureChallengeWindowSize": "FULL_SCREEN", "javaEnabled": false, "language": "en-US", "screenHeight": 768, "screenWidth": 1366, "timeZone": -480, "colorDepth": 24 } } }
AUTHENTICATE PAYER response example - 3DS Frictionless Success
{ "authentication": { "3ds": { "acsEci": "02", "authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId": "c398b089-1ecb-4904-8309-f210b545654f" }, "3ds2": { "3dsServerTransactionId": "b2bacc6e-6586-45b9-90ee-4cd2f436596e", "acsReference": "MPGS_ACS_SANDBOX", "acsTransactionId": "067538cd-23c6-425c-8415-7498663197fb", "authenticationScheme": "MASTERCARD", "directoryServerId": "A000000004", "dsReference": "MC_DS_SANDBOX", "dsTransactionId": "c398b089-1ecb-4904-8309-f210b545654f", "methodSupported": "NOT_SUPPORTED", "protocolVersion": "2.2.0", "requestorId": "MAS00001_INT_MPGS_DLD33102UQ18DHW2V", "requestorName": "Visa MP1", "transactionStatus": "Y" }, "amount": 101.00, "payerInteraction": "NOT_REQUIRED", "redirect": { "html": "<div id=\"threedsFrictionLessRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"challengeFrame\" name=\"challengeFrame\"> </iframe> <form id=\"threedsFrictionLessRedirectForm\" method=\"POST\" action=\"https://dl01aspall1mv.mpgsdev.mastercard.int/merchantSimulator/jsp/simple/output.jsp\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"order.id\" value=\"NMC_608216124\" /> <input type=\"hidden\" name=\"transaction.id\" value=\"1\" /> <input type=\"hidden\" name=\"response.gatewayRecommendation\" value=\"PROCEED\" /> <input type=\"hidden\" name=\"result\" value=\"SUCCESS\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsFrictionLessRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode removeChild(e); } } </script> </div>" }, "time": "2024-07-16T16:14:11.542Z", "version": "3DS2" }, "device": { "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36" }, "merchant": "D3S2_SOMB", "order": { "amount": 101.00, "authenticationStatus": "AUTHENTICATION_SUCCESSFUL", "creationTime": "2024-07-16T16:14:03.181Z", "currency": "USD", "id": "NMC_608216124", "lastUpdatedTime": "2024-07-16T16:14:11.532Z", "merchantCategoryCode": "1324", "status": "AUTHENTICATED", "subMerchant": { "address": { "city": "Pune", "company": "Pune", "country": "IND", "postcodeZip": "411047", "stateProvince": "Pun", "street": "Pune", "street2": "Pune" }, "bankIndustryCode": "1324", "disputeContactPhone": "+91 00000000", "email": "test@noreply.com", "identifier": "828680860811", "phone": "00000000", "registeredName": "MPGS", "tradingName": "Visa MP1", "websiteUrl": "https://test@noreply.com", "marketplaceId": "AMAZONMAR!!", "governmentCountryCode": "IND" }, "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalRefundedAmount": 0, "valueTransfer": { "accountType": "NOT_A_TRANSFER" } }, "response": { "gatewayCode": "APPROVED", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "number": "543357xxxxxx0016", "scheme": "MASTERCARD" } }, "type": "CARD" }, "timeOfLastUpdate": "2024-07-16T16:14:11.532Z", "timeOfRecord": "2024-07-16T16:14:03.181Z", "transaction": { "acquirer": { "merchantId": "9809" }, "amount": 101.00, "authenticationStatus": "AUTHENTICATION_SUCCESSFUL", "currency": "USD", "id": "1", "type": "AUTHENTICATION" }, "version": "85" }
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": "Pune", "company": "Pune", "country": "IND", "postcodeZip": "411047", "stateProvince": "Pun", "street": "Pune", "street2": "Pune" }, "bankIndustryCode": "1324", "disputeContactPhone": "+91 00000000", "email": "test@noreply.com", "identifier": "828680860811", "phone": "00000000", "registeredName": "MPGS", "tradingName": "Visa MP1", "websiteUrl": "https://test@noreply.com", "marketplaceId": "AMAZONMAR!!", "governmentCountryCode": "IND" }, "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": "85" }