---
title: "Payment facilitators"
description: "Learn what additional information you must provide with your transactions if you are a payment facilitator."
url: "https://docs.adyen.com/platforms/in-person-payments/payment-facilitators"
source_url: "https://docs.adyen.com/platforms/in-person-payments/payment-facilitators.md"
canonical: "https://docs.adyen.com/platforms/in-person-payments/payment-facilitators"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Payment facilitators

Learn what additional information you must provide with your transactions if you are a payment facilitator.

[View source](/platforms/in-person-payments/payment-facilitators.md)

If you are a [payment facilitator](/get-started-with-adyen/adyen-glossary#payment-facilitator-payfac), 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

In addition to the [general requirements](/platforms/in-person-payments#requirements) for in-person payments with an Adyen for Platforms integration, take into account the following requirements and limitations.

| Requirement                                                    | Description                                                                                                                                                                                                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Integration type**                                           | A [Terminal API integration](/point-of-sale/design-your-integration/terminal-api) with payment terminals or with a [Mobile solution](/point-of-sale/ipp-mobile), or a [standalone solution](/point-of-sale/standalone).                                |
| **[API credentials](/development-resources/api-credentials/)** | To add user data to the store configuration, you must have an API credential that you can use for the [Management API](https://docs.adyen.com/api-explorer/Management/latest/overview) and that has the **Management API—Stores read and write** role. |
| **Limitations**                                                | The standalone solution only supports adding user data through the store configuration.                                                                                                                                                                |

## 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](#store-configuration). This is mainly intended for standalone terminals, but can also be used for integrated terminals.
* By adding [fields in the Terminal API requests](#tapi-request).

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 or a Mobile solution, 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 `id`of the user's store.\
   To find that value, you can make a GET [/stores](https://docs.adyen.com/api-explorer/Management/latest/get/stores) request (or a GET [/merchants/{merchantId}/stores](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/stores) request).

2. Make a PATCH [/stores/{storeId}](https://docs.adyen.com/api-explorer/Management/latest/patch/stores/\(storeId\)) request with:

   * A [subMerchantData](https://docs.adyen.com/api-explorer/Management/latest/patch/stores/\(storeId\)#request-subMerchantData) object with the following parameters.

     | Parameter | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                  |
     | --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
     | `email`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The email address associated with the user's account.                                                                                                                                                                                                                                                        |
     | `id`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique identifier of your user. Must be an alphanumerical string with a maximum length of 15 characters.                                                                                                                                                                                                |
     | `mcc`     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The 4-digit [Merchant Category Code](/get-started-with-adyen/adyen-glossary/#merchant-category-code) of your user.                                                                                                                                                                                           |
     | `name`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of your user. Based on scheme specifications, this value will overwrite (part of) the [transaction description](/account/transaction-description/#without-customization) that will appear on the shopper's bank statement. Must be an alphanumerical string with a maximum length of 22 characters. |

   **Add user data to an existing store**

   #### curl

   ```bash
   curl https://management-test.adyen.com/v3/stores/ST322LJ223223K5F4SQNR9XL5 \
   -H 'content-type: application/json' \
   -H 'x-api-key: ADYEN_API_KEY' \
   -X PATCH \
   -d '{
      "subMerchantData":{
         "email": "test-merchant@example.com",
         "id": "12345",
         "mcc": "5734",
         "name":"Test Merchant"
      }
   }'
   ```

   #### Java

   ```java
   // Adyen Java API Library v39.2.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.model.management.*;
   import java.time.OffsetDateTime;
   import java.util.*;
   import com.adyen.service.management.*;

   Client client = new Client("ADYEN_API_KEY", Environment.TEST);

   // Create the request object(s)
   UpdateStoreRequest updateStoreRequest = new UpdateStoreRequest();

   // Send the request
   AccountStoreLevelApi service = new AccountStoreLevelApi(client);
   Store response = service.updateStoreById("storeId", updateStoreRequest, null);
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v28.1.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Model\Management\UpdateStoreRequest;
   use Adyen\Service\Management\AccountStoreLevelApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_API_KEY");
   $client->setEnvironment(Environment::TEST);


   // Create the request object(s)
   $updateStoreRequest = new UpdateStoreRequest();
   $updateStoreRequest;

   // Send the request
   $service = new AccountStoreLevelApi($client);
   $response = $service->updateStoreById('storeId', $updateStoreRequest);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v32.0.1
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.Management;
   using Adyen.Service.Management;

   var config = new Config()
   {
       XApiKey = "ADYEN_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Create the request object(s)
   UpdateStoreRequest updateStoreRequest = new UpdateStoreRequest

   };

   // Send the request
   var service = new AccountStoreLevelService(client);
   var response = service.UpdateStoreById("storeId", updateStoreRequest);
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v28.1.0
   const { Client, ManagementAPI } = require('@adyen/api-library');

   const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });

   // Create the request object(s)
   const updateStoreRequest = {
     subMerchantData: {
       email: "test-merchant@example.com",
       id: "12345",
       mcc: "5734",
       name: "Test Merchant"
     }
   }

   // Send the request
   const managementAPI = new ManagementAPI(client);
   const response = managementAPI.AccountStoreLevelApi.updateStoreById("storeId", updateStoreRequest);
   ```

   #### Go

   ```go
   // Adyen Go API Library v21.0.0
   import (
     "context"
     "github.com/adyen/adyen-go-api-library/v21/src/common"
     "github.com/adyen/adyen-go-api-library/v21/src/adyen"
     "github.com/adyen/adyen-go-api-library/v21/src/management"
   )
   client := adyen.NewClient(&common.Config{
     ApiKey:      "ADYEN_API_KEY",
     Environment: common.TestEnv,
   })

   // Create the request object(s)
   updateStoreRequest := management.UpdateStoreRequest,
   }

   // Send the request
   service := client.Management()
   req := service.AccountStoreLevelApi.UpdateStoreByIdInput("storeId").UpdateStoreRequest(updateStoreRequest)
   res, httpRes, err := service.AccountStoreLevelApi.UpdateStoreById(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.5.1
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = "ADYEN_API_KEY"
   adyen.client.platform = "test" # The environment to use library in.

   # Create the request object(s)
   json_request = {
     "subMerchantData": {
       "email": "test-merchant@example.com",
       "id": "12345",
       "mcc": "5734",
       "name": "Test Merchant"
     }
   }

   # Send the request
   result = adyen.management.account_store_level_api.update_store_by_id(request=json_request, storeId="storeId")
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v10.3.0
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_API_KEY'
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   request_body = {
     :subMerchantData => {
       :email => 'test-merchant@example.com',
       :id => '12345',
       :mcc => '5734',
       :name => 'Test Merchant'
     }
   }

   # Send the request
   result = adyen.management.account_store_level_api.update_store_by_id(request_body, 'storeId')
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v28.1.0
   import { Client, ManagementAPI, Types } from "@adyen/api-library";

   const client = new Client({ apiKey: "ADYEN_API_KEY", environment: "TEST" });

   // Create the request object(s)
   const updateStoreRequest: Types.management.UpdateStoreRequest = 
   };

   // Send the request
   const managementAPI = new ManagementAPI(client);
   const response = managementAPI.AccountStoreLevelApi.updateStoreById("storeId", updateStoreRequest);
   ```

   You can also make a PATCH request to the [/merchants/{merchantId}/stores/{storeId}](https://docs.adyen.com/api-explorer/Management/latest/patch/merchants/\(merchantId\)/stores/\(storeId\)) endpoint 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](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-subMerchantData) object when you create a new store using a POST [/stores](https://docs.adyen.com/api-explorer/Management/latest/post/stores) request (or a POST [/merchants/{merchantId}/stores](https://docs.adyen.com/api-explorer/Management/latest/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](https://en.wikipedia.org/wiki/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](/account/transaction-description/#without-customization) 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](/get-started-with-adyen/adyen-glossary/#merchant-category-code) of your user.                                                                                                                                                                                           |

   **additionalData JSON object**

   ```json
   {
       "additionalData": {
           "subMerchantId": "123456789",
           "subMerchantCity": "São Paulo",
           "subMerchantCountry": "BRA",
           "subMerchantName": "Empresa XYZ Ltda.",
           "subMerchantPostalCode": "04386040",
           "subMerchantStreet": "Rua Funcionarios 952",
           "subMerchantTaxId": "56861752509",
           "subMerchantMcc": "7622"
       }
   }
   ```

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

   **Converted to a Base64-encoded string**

   ```sh
   ewogICAiYWRkaXRpb25hbERhdGEiOnsKICAgICAgInN1Yk1lcmNoYW50SWQiOiIxMjM0NTY3ODkiLAogICAgICAic3ViTWVyY2hhbnRDaXR5IjoiU8OjbyBQYXVsbyIsCiAgICAgICJzdWJNZXJjaGFudENvdW50cnkiOiJCUkEiLAogICAgICAic3ViTWVyY2hhbnROYW1lIjoiRW1wcmVzYSBYWVogTHRkYS4iLAogICAgICAic3ViTWVyY2hhbnRQb3N0YWxDb2RlIjoiMDQzODYwNDAiLAogICAgICAic3ViTWVyY2hhbnRTdHJlZXQiOiJSdWEgRnVuY2lvbmFyaW9zIDk1MiIsCiAgICAgICJzdWJNZXJjaGFudFRheElkIjoiNTY4NjE3NTI1MDkiLAogICAgICAic3ViTWVyY2hhbnRNY2MiOiI3NjIyIgogICB9Cn0=
   ```

3. [Make a Terminal API payment request](/point-of-sale/basic-tapi-integration/make-a-payment) with the Base64-encoded string as the [SaleToAcquirerData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-SaleData-SaleToAcquirerData) value.

   **Add user data to a Terminal API request**

   ```json
   {
       "SaleToPOIRequest":{
           "MessageHeader":{
               "ProtocolVersion":"3.0",
               "MessageClass":"Service",
               "MessageCategory":"Payment",
               "MessageType":"Request",
               "SaleID":"POSSystemID12345",
               "ServiceID":"0207111104",
               "POIID":"V240mPlus-324688179"
           },
           "PaymentRequest":{
               "SaleData":{
                   "SaleTransactionID":{
                       "TransactionID":"27908",
                       "TimeStamp":"2025-08-07T10:11:04+00:00"
                   },
                   "SaleToAcquirerData": "ewogICAiYWRkaXRpb25hbERhdGEiOnsKIC...ICB9Cn0="
               },
               "PaymentTransaction":{
                   "AmountsReq":{
                       "Currency":"BRL",
                       "RequestedAmount":120.00
                   }
               }
           }
       }
   }
   ```

Note that the response does not echo the specified user data.

## Combining user data and split instructions

It is possible to provide both user data and [split instructions](/platforms/in-person-payments/split-transactions) in the same Terminal API request.

However, you must provide all the data in the same way: as a JSON object converted to a Base64-encoded string. The reason is that the Terminal API cannot pass on user data that is formatted as concatenated key-value pairs.

Here is an example:

1. Create an `additionalData` JSON object with the user data and the split instructions.

   **JSON object combining data types**

   ```json
   {
       "additionalData": {
           "subMerchantId": "123456789",
           "subMerchantCity": "São Paulo",
           "subMerchantCountry": "BRA",
           "subMerchantName": "Empresa XYZ Ltda.",
           "subMerchantPostalCode": "04386040",
           "subMerchantStreet": "Rua Funcionarios 952",
           "subMerchantTaxId": "56861752509",
           "subMerchantMcc": "7622",
           "split.api": "1",
           "split.nrOfItems": "3",
           "split.totalAmount": "8000",
           "split.currencyCode": "USD",
           "split.item1.amount": "7500",
           "split.item1.type": "BalanceAccount",
           "split.item1.account": "BA00000000000000000000001",
           "split.item1.reference": "Your reference for the sale amount",
           "split.item1.description": "Your description for the sale amount",
           "split.item2.amount": "500",
           "split.item2.type": "Commission",
           "split.item2.reference": "Your reference for your commission",
           "split.item2.description": "Your description for your commission",
           "split.item3.type": "PaymentFee",
           "split.item3.account": "BA00000000000000000000001",
           "split.item3.reference": "Your reference for the payment fee",
           "split.item3.description": "Your description for the payment fee"
       }
   }
   ```

2. Encode the JSON object to Base64.

   **Converted to a Base64-encoded string**

   ```bash
    
   ```

3. Pass the Base64-encoded string in the `SaleData.SaleToAcquirerData` parameter of your Terminal API payment request.

## See also

* [Online payments by payment facilitators](/platforms/online-payments/payment-facilitators/)
