Payment facilitators

If you are a payment facilitator, card schemes require you to provide certain data about your sub-merchant with each transaction. That is because your sub-merchant is considered the Merchant of Record when a transaction is facilitated by you .

Adyen automatically adds certain sub-merchant data to transactions that you facilitate. The remaining data must be supplied by you. This page explains the ways you can do that.

Requirements

Methods to add sub-merchant data

Adyen automatically adds certain sub-merchant data to transactions that you facilitate. The remaining sub-merchant data must be supplied by you.

There are two methods to add sub-merchant data:

• Through the configuration of the store. This is mainly intended for standalone terminals, but can also be used for integrated terminals.
• By adding fields in the Terminal API requests.

If your sub-merchant has standalone terminals, you must use the store configuration method. For integrated terminals you can use either method or both. When using both methods, the Terminal API request overrides the store configuration.

When you add fields to requests, you only need to do this for Terminal API payment requests and Terminal API referenced and unreferenced refund requests. Adding fields is not necessary for payment modifications that are not Terminal API requests, such as manual captures and authorization adjustments. For those non-Terminal API requests, Adyen adds the sub-merchant data from the initial payment.

Add to the store configuration

If your sub-merchant uses standalone terminals, you must add sub-merchant data to the sub-merchant's store through the Management API. Adyen then adds this data before sending requests for authorization.

If your sub-merchant uses a POS system with integrated terminals, you can also add sub-merchant data to the sub-merchant's store. When necessary, you can override the data specified for the store by adding sub-merchant data to individual Terminal API requests.

To add sub-merchant data to an existing store:

1. Make sure you have the idof the sub-merchant's store.
   To find that value, you can make a GET /stores request (or a GET /merchants/{merchantId}/stores request).

2. Make a PATCH /stores/{storeId} request with:

   • A subMerchantData object with the following parameters.

     Parameter	Required	Description
     email		The email address associated with the sub-merchant's account.
     id		Your unique identifier of your sub-merchant. Must be an alphanumerical string with a maximum length of 15 characters.
     mcc		The 4-digit Merchant Category Code of your sub-merchant.
     name		The name of your sub-merchant. Based on scheme specifications, this value will overwrite (part of) the transaction description that will appear on the shopper's bank statement. Must be an alphanumerical string with a maximum length of 22 characters.

   You can also make a PATCH request to /merchants/{merchantId}/stores/{storeId} using the same subMerchantData object.

3. In the response note that this contains the full details of the store, including the subMerchantData you submitted.

You can also include a subMerchantData object when you create a new store using a POST /stores request (or a POST /merchants/{merchantId}/stores request).

Add to the Terminal API request

To add data about your sub-merchant in your Terminal API request:

1. Create an additionalData JSON object with the following parameters:

   Parameter	Description
   subMerchantId	Your unique identifier of your sub-merchant. Must be an alphanumerical string with a maximum length of 19 characters.
   subMerchantCity	The city of your sub-merchant's address. Must be an alphanumeric string with a maximum length of 13 characters.
   subMerchantCountry	The three-letter country code in ISO 3166-1 alpha-3 format of your sub-merchant's address. For example, BRA for Brazil.
   subMerchantName	The name of your sub-merchant. Based on scheme specifications, this value will overwrite (part of) the transaction description that will appear on the shopper's bank statement. Must be an alphanumerical string with a maximum length of 22 characters.
   subMerchantPostalCode	The postal code of your sub-merchant's address. Maximum length: 8 digits.
   subMerchantStreet	The street and house number of your sub-merchant's address.
   subMerchantTaxId	The tax ID or your sub-merchant.
   subMerchantMcc	The 4-digit Merchant Category Code of your sub-merchant.

2. Encode the additionalData JSON object to Base64. You will pass the resulting string in SaleData.SaleToAcquirerData.

3. Send a Terminal API PaymentRequest with the Base64-encoded string as the SaleToAcquirerData value.

Note that the response does not echo the specified sub-merchant data.

See also