Payment-method icon

Card scheme requirements for payment facilitators

Send sub-merchant transactions to Adyen to comply with Visa and Mastercard requirements


This documentation is intended for payment facilitators who are not using the Adyen for Platforms (AfP) solution.

If you are a payment facilitator that processes card transactions for sub-merchants, Visa and Mastercard require you to send certain data points with each transaction. These data points must refer to the sub-merchant, who is considered the Merchant of Record when a transaction is passed through a payment facilitator.

Send sub-merchant data points with a transaction

During the /payments authorization for each transaction, Visa and Mastercard require data points that specify the following information about the sub-merchant:

  • Unique identifier: You must assign a unique identifier to each of your sub-merchants.
  • Name: You must provide an accurate name for the sub-merchant that is present on the shopper's statement. For Mastercard, this includes an aggregator prefix.
    Contact the Support Team to get a Mastercard aggregator prefix.
  • Location: You must provide the sub-merchant's location as the location of the transaction.

Required parameters

You must send additionalData parameters with the /payments authorization. For cancellations, captures, and refunds, Adyen automatically populates sub-merchant details from the initial payment.

Submit your request using AdditionalDataSubMerchant parameters. See the API documentation to view specific formatting requirements for each parameter.

The [subSellerNr] is always 1. Submit all additionalData parameters as:

Required parameter Description
additionalData.subMerchant.numberOfSubSellers The number of sub-merchants in the transaction. For Payment Facilitators not using AfP, this value must be 1.
additionalData.subMerchant.subSeller[subSellerNr].id A unique identifier assigned by the payment facilitator.
additionalData.subMerchant.subSeller[subSellerNr].taxId The tax ID of the sub-merchant: an 11-digit CPF or 14-digit CNPJ.
Required only in Brazil.
additionalData.subMerchant.subSeller[subSellerNr].mcc The sub-merchant's 4-digit Merchant Category Code (MCC).
Required only in Brazil.
additionalData.subMerchant.subSeller[subSellerNr].name The name of the sub-merchant.
additionalData.subMerchant.subSeller[subSellerNr].street The street name and house number of the sub-merchant's address.
additionalData.subMerchant.subSeller[subSellerNr].postalCode The postal code of the sub-merchant's address, without dashes.
Required only in Brazil, Canada, the United States, and for domestic in-person payments in Ireland.
additionalData.subMerchant.subSeller[subSellerNr].city The city of the sub-merchant's address.
additionalData.subMerchant.subSeller[subSellerNr].state The state code of the sub-merchant's address, if applicable to the country.
additionalData.subMerchant.subSeller[subSellerNr].country The three-letter ISO country code of the sub-merchant's address.

Automatically collected parameters

Your API request contains two additional data points that are automatically collected from your account properties. Do not send these data points manually. The two data points are:

  • paymentFacilitatorIds: Your payment facilitator ID. Both Visa and Mastercard create an ID for you.
    For example: AdyenVisa_US_WF_400224: '12345'
  • aggregatorPrefix: Your 25-character aggregator prefix.
    For example: PayfacName*SubmerchantName.

Sample request

See also