--- 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/point-of-sale/payment-facilitators" source_url: "https://docs.adyen.com/point-of-sale/payment-facilitators.md" canonical: "https://docs.adyen.com/point-of-sale/payment-facilitators" last_modified: "2026-05-25T12:55:00+02:00" language: "en" --- # Payment facilitators Learn what additional information you must provide with your transactions if you are a payment facilitator. [View source](/point-of-sale/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 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 Before you begin, 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 sub-merchant 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 sub-merchant data through the store configuration. | ## 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](#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 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 or a Mobile solution, 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 `id`of the sub-merchant'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 sub-merchant's account. | | `id` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique identifier of your sub-merchant. 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 sub-merchant. | | `name` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of your sub-merchant. 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 sub-merchant 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 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 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](https://en.wikipedia.org/wiki/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](/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 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](/get-started-with-adyen/adyen-glossary/#merchant-category-code) of your sub-merchant. | **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 sub-merchant 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 sub-merchant data. ## See also * [Set up standalone](/point-of-sale/standalone/standalone-build/set-up-standalone/) * [Online payments by payment facilitators](/payment-methods/cards/payment-facilitators/)