Subgateway Merchants

Subgateways can use the gateway without having to set up a merchant profile for each of their merchants (client merchants) in the gateway.

If your merchant profile in the gateway is configured as a subgateway merchant profile, you can instead submit the merchant configuration details required to process the request on the API request.

Subgateway merchant functionality is supported by API version 53 and above, only on API requests for the Authentication API.
The client merchant's configuration details only need to be provided on the Initiate Authentication request — the gateway automatically applies the details to both Initiate Authentication and Authenticate Payer operations.
If your merchant profile is configured as a subgateway merchant profile you will not be able to submit transactions for processing without providing subgateway merchant details.
The subgateway merchant functionality does not provide support for Aggregators (also called Payment Facilitators), i.e., it does not allow you to submit transactions on behalf of another merchant (sub-merchant). For details about the gateway's aggregator functionality, see Aggregator Support.

Prerequisites

Your payment service provider must enable the subgateway merchant functionality on your merchant profile in the gateway.

Submitting Transactions for 3DS

When using the Authentication API on a subgateway merchant profile you must provide the following details for your client merchant on the Initiate Authentication request:

client merchant details including ID, name, website URL and address
merchant acquirer link details, including the Acquirer Merchant ID for the client merchant
3DS configuration details for your client merchant

In addition, you must provide the transaction frequency on the Authenticate Payer request.

The rules for the gateway to determine if 3DS2 or 3DS1 (including fallback to 3DS1) should be performed are the same for subgateway merchants as for any other merchants. See 3-D Secure Authentication for details.

Initiate Authentication API Reference [REST] [NVP]

Authenticate Payer API Reference [REST] [NVP]

Client Merchant Details

You must provide the following details for your client merchant on the Initiate Authentication request:

subgatewayMerchant.id: Your identifier for the client merchant, i.e., the merchant for whom you are submitting the request.
subgatewayMerchant.name: The client merchant name.
subgatewayMerchant.websiteUrl: The client merchant's website URL.
subgatewayMerchant.address.*: The client merchant's address details.
order.merchantCategoryCode: The client merchant's Merchant Category Code (4-digit code used to classify a business by the type of goods or services it offers).

Merchant Acquirer Link Details

For each acquirer configured against your gateway merchant profile, for which the client merchant can process transactions, you must provide the client merchant's Acquirer Merchant ID on the Initiate Authentication request:

subgatewayMerchant.acquirer[n].id: The gateway's Acquirer ID for the acquirer for which you are providing the client merchant's Acquirer Merchant ID.
subgatewayMerchant.acquirer[n].acquirerMerchantId: The client's Acquirer Merchant ID for this acquirer.
subgatewayMerchant.acquirer[n].merchantCategoryCode: The client merchant's Merchant Category Code for this acquirer. You only need to provide this value if this acquirer needs a different MCC value than the other acquirer links you may have specified. If the same MCC applies to all acquirers, simply use order.merchantCategoryCode
Do not provide this field if you provide subgatewayMerchant.authentication[n].acquirerBIN on your request.

The gateway will only process requests where you have provided the client's Acquirer Merchant ID for the acquirer that has been identified as the acquirer used to process the request (based on the transaction routing decision made by the gateway, i.e., the identified Merchant Acquirer Link).

You are only allowed to submit Acquirer Merchant IDs for which you have been configured by your payment service provider. Please contact your payment service provider if you submit a value you have not been configured for.

3DS2 Details

You must provide the 3DS2 configuration details for your client merchant on the Initiate Authentication request including:

subgatewayMerchant.authentication[n].protocol: The authenticate scheme for which the client merchant can perform 3DS2 payer authentications.
subgatewayMerchant.authentication[n].3DS2.requestorId Only required for American Express SafeKey.
subgatewayMerchant.authentication[n].3DS2.requestorName (Optional) Only required for .

Mastercard SecureCode and Verified By Visa only require the authentication scheme to be identified in the subgatewayMerchant.authentication[n].protocol field. The Requestor ID and Requestor Name are generated by the gateway. The value generated by the gateway (and submitted to the MI Server) will be returned in the Initiate Authentication response.

For American Express SafeKey, you must provide all the details including Requestor ID and Requestor Name.

The gateway will only process requests for which you have provided the protocol (and where required, Requestor ID and Requestor Name) in the request. For example, if you provide a card number that the gateway identifies as a American Express card but you have not provided subgatewayMerchant.authentication[n].protocol=AMEX_SAFEKEY in the request, the request is rejected by the gateway.

3DS1 Details

The gateway provides 3DS1 support for Mastercard SecureCode, Verified by Visa and American Express Safekey.

You must provide the 3DS1 configuration details for your client merchant on the Initiate Authentication request including:

subgatewayMerchant.acquirer[n].3DS1.masterCardSecureCode.merchantId
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId
subgatewayMerchant.acquirer[n].3DS1.amexSafeKey.merchantId

These must be provided for each acquirer (identified by subgatewayMerchant.acquirer[n]) for which the client merchant can perform 3DS1 payer authentications.

Acquirer Selection

If your payment service provider has configured you with more than one acquirer link with the same currency, card type and line of business combination, you are required to identify the acquirer you want to use for processing the authentication using the subgatewayMerchant.acquirer[n].id field in the Initiate Authentication request.

If the gateway is not able to uniquely identify the acquirer it will return an error message.

Test your Integration

To test your integration you can use your TEST merchant profile in the Production environment. See Test and Go Live.