Audience
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:
additionalData.subMerchant.subSeller1.[parameter]
| 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 Customer Area > Account Data Properties. You should not manually send these data points:
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
curl https://checkout-test.adyen.com/v69/payments/ \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"merchantAccount":"YOUR_MERCHANT_ACCOUNT",
"amount": {
"currency":"EUR",
"value":10000
},
"reference":"YOUR_UNIQUE_REFERENCE",
"paymentMethod" : {
"number" : "CARD_NUMBER",
"expiryMonth" : "EXPIRY_MONTH",
"expiryYear" : "EXPIRY_YEAR",
"cvc" : "CVC",
"holderName" : "HOLDER_NAME",
"type" : "scheme"
},
"additionalData" : {
"subMerchant.numberOfSubSellers" : 1,
"subMerchant.subSeller1.id" : "12345",
"subMerchant.subSeller1.name" : "Test Merchant",
"subMerchant.subSeller1.street" : "Street Address",
"subMerchant.subSeller1.postalCode" : "POSTAL_CODE",
"subMerchant.subSeller1.city" : "CITY",
"subMerchant.subSeller1.state" : "STATE",
"subMerchant.subSeller1.country" : "COUNTRY"
}
}'