Payment facilitators

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

Adyen automatically adds certain user 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 user data

Adyen automatically adds certain user data to transactions facilitated by your platform. The remaining user data must be supplied by you.

There are two methods to add user 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 user 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 user uses standalone terminals, you must add user data to the user's store through the Management API. Adyen then adds this data before sending requests for authorization.

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

To add user data to an existing store:

1. Make sure you have the idof the user'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 user's account.
     id		Your unique identifier of your user. Must be an alphanumerical string with a maximum length of 15 characters.
     mcc		The 4-digit Merchant Category Code of your user.
     name		The name of your user. 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 user in your Terminal API request:

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

   Parameter	Description
   subMerchantId	Your unique identifier of your user. Must be an alphanumerical string with a maximum length of 19 characters.
   subMerchantCity	The city of your user'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 user's address. For example, BRA for Brazil.
   subMerchantName	The name of your user. 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 user's address. Maximum length: 8 digits.
   subMerchantStreet	The street and house number of your user's address.
   subMerchantTaxId	The tax ID or your user.
   subMerchantMcc	The 4-digit Merchant Category Code of your user.

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 user data.

See also