Aggregator Support

The Suncorp 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.


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
  • Standalone CAPTURE
  • Standalone REFUND

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

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


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.


If you are acting as an aggregator you may not use Tokenization functionality. The gateway rejects transaction requests with sub-merchant details for merchants enabled for Tokenization.

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 2.0
  • Verified by Visa 2.0
  • Amex SafeKey 2.0

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.

Submitting Transactions for 3DS2

You must provide the following details for your sub-merchant on the Initiate Authentication 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
  • (mandatory for all supported 3DS2 schemes)
  • order.subMerchant.address.* (other address fields)

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 each authentication scheme (identified by order.subMerchant.authentication[n].protocol) for which the sub-merchant can perform 3DS2 payer authentications, you must also provide the Requestor ID and Requestor Name, except for Mastercard SecureCode and Verified By Visa.

For Mastercard SecureCode and Verified By Visa, you are not required to provide authentication details. The Requestor ID and Requestor Name are generated by the gateway.

For Amex SafeKey, if the Requestor ID and Requestor Name for the sub-merchant are not available, the gateway will use the Requestor ID and Requestor Name configured on your merchant profile.

Copyright © 2021 Suncorp