# Aggregator source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/multi-party-payment-model/aggregator/index.md ## Overview {#overview} 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 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. Warning: * Aggregator functionality is supported for Mastercard, Visa, and American Express. * 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 Mastercard Gateway API requests for AMEX require the email and telephone number of the payment aggregator in addition to the sub-merchant details. The following methods are supported: | Integration methods | Payment methods | Operations\* | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | * [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-checkout/index.md) * [Hosted Session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/index.md) * [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md) * [Hosted Batch](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/index.md) | All except alternative payment methods ([APM](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/index.md)) | [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * [STANDALONE CAPTURE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * [STANDALONE REFUND](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * [VERIFY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * [INITIATE CHECKOUT](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#hosted-checkout) * [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) * [INITIATE AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) \* Where sub-merchant details are included. | ## Prerequisites {#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 {#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 * INITIATE AUTHENTICATION When submitting the transaction, provide the following sub-merchant details in the order.subMerchant object of the request: * `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.city` * `order.subMerchant.address.country` * `order.subMerchant.phone` * `order.subMerchant.disputeContactPhone` * `order.subMerchant.marketplaceId` * `order.subMerchant.governmentCountryCode` Alert: The `order.subMerchant.marketplaceId` and `order.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](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [REFUND](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) 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](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). ## Sharing Hosted Checkout {#sharing-hosted-checkout} If you want to provide your sub-merchants the [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-checkout/index.md) functionality, you must provide them with an interface to your Hosted Checkout integration. To share your Hosted Checkout with your sub-merchants (from the API v64 onwards): 1. Submit an [INITIATE CHECKOUT](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#hosted-checkout) request and include the sub-merchant order details in it. The response returns a session ID. 2. 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. 3. When the payer's browser is returned to your app, redirect the payer to the sub-merchant's app. Alert: Never give a sub-merchant your gateway credentials. This would enable them to access the transactions of your other sub-merchants. ## Enabling EMV 3-D Secure authentication {#enabling-emv-3-d-secure-authentication} To enable your sub-merchants to use [EMV 3-D Secure authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md) through the gateway, you must submit the relevant sub-merchant details in the [INITIATE AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#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 Identity Check * Visa Secure * American Express SafeKey * UnionPay * Jaywan Warning: Check with your PSP which schemes they support. If the authentication is followed by a payment using an AUTHORIZE or PAY transaction that references the EMV 3-D Secure 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 {#prerequisites-1} On your merchant profile, you must be enabled for the EMV 3-D Secure authentication scheme that the sub-merchant wants to use to perform EMV 3-D Secure payer authentications. ### Step 1: Initiate Authentication {#step-1-initiate-authentication} Create the INITIATE AUTHENTICATION request, following the general instructions (for [Payer Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) or [JavaScript API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md) 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` Alert: The `order.subMerchant.marketplaceId` and `order.subMerchant.governmentCountryCode` are available from the v85 onwards. * Sub-merchant's EMV 3-D Secure 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` Warning: * For American Express Safekey, the gateway will use the EMV 3-D Secure 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. * For UnionPay EMV 3-D Secure, the gateway will use the submerchant identifier as the EMV 3-D Secure Requestor ID and the submerchant trading name as the EMV 3-D Secure Requestor Name. You can provide the authentication details to override these values. Do not provide authentication details for supported authentication schemes (see the list above). The EMV 3-D Secure Requestor ID and EMV 3-D Secure Requestor Name are generated by the gateway. INITIATE AUTHENTICATION request and response example | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 | [Click here to download Postman Collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api) - the path to this operation is **/Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/1. INITIATE AUTHENTICATION** ```json { "apiOperation": "INITIATE_AUTHENTICATION", "authentication": { "acceptVersions": "3DS2", "channel": "PAYER_BROWSER", "purpose": "PAYMENT_TRANSACTION" }, "order": { "currency": "{{currency}}", "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": "{{fpan}}" } } } } ``` ```json { "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 {#step-2-authenticate-payer} The [AUTHENTICATE PAYER](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request is identical for aggregators and non-aggregators. Follow the general instructions (for [Payer Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) or [JavaScript API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md) implementation). | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 | [Click here to download Postman Collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api) - the path to this operation is **/Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/4. AUTHENTICATE PAYER** AUTHENTICATE PAYER request and response example ```json { "apiOperation": "AUTHENTICATE_PAYER", "authentication": { "redirectResponseUrl": "https://{{host}}/api/documentation/integrationGuidelines/index.html" }, "order": { "currency": "{{currency}}", "amount": 101.00 }, "sourceOfFunds": { "provided": { "card": { "number": "{{fpan}}", "expiry": { "month": "{{expMonth}}", "year": "{{expYear}}" } } } }, "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 } } } ``` ```json { "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 {#step-3-use-the-authentication-in-a-payment} The authentication result is used in a payment operation identical for aggregators and non-aggregators. Follow the general instructions (for [Payer Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) or [JavaScript API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md) implementation). [Click here to download Postman Collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api) - the path to this operation is **/Security and Fraud Prevention/3D Secure Authentication/Authentication as Aggregator/6. AUTHORIZE** | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------| | POST | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/2 | AUTHORIZE request and response example ```json { "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" } } ``` ```json { "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" } ```