{"title":"Payment facilitators","category":"default","creationDate":1776961628,"content":"<p>If you are a <a href=\"\/pt\/get-started-with-adyen\/adyen-glossary#payment-facilitator-payfac\" target=\"_blank\">payment facilitator<\/a>, 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 .<\/p>\n<p>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.<\/p>\n<h2>Requirements<\/h2>\n In addition to the <a href=\"\/platforms\/in-person-payments#requirements\">general requirements<\/a> for in-person payments with an Adyen for Platforms integration, take into account the following requirements and limitations. <table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\">A <a href=\"\/pt\/point-of-sale\/design-your-integration\/terminal-api\">Terminal API integration<\/a> with payment terminals or with a <a href=\"\/pt\/point-of-sale\/ipp-mobile\">Mobile solution<\/a>, or a <a href=\"\/pt\/point-of-sale\/standalone\">standalone solution<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/pt\/development-resources\/api-credentials\/\">API credentials<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">To add  user  data to the store configuration, you must have an API credential that you can use for the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Management API<\/a> and that has the <strong>Management API\u2014Stores read and write<\/strong> role.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Limitations<\/strong><\/td>\n<td style=\"text-align: left;\">The standalone solution only supports adding  user  data through the store configuration.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Methods to add  user  data<\/h2>\n<p>Adyen automatically adds certain  user  data to transactions  facilitated by your platform. The remaining  user  data must be supplied by you.<\/p>\n<p>There are two methods to add  user  data:<\/p>\n<ul>\n<li>Through the <a href=\"#store-configuration\">configuration of the store<\/a>. This is mainly intended for standalone terminals, but can also be used for integrated terminals.<\/li>\n<li>By adding <a href=\"#tapi-request\">fields in the Terminal API requests<\/a>.<\/li>\n<\/ul>\n<p>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.<\/p>\n<p>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.<\/p>\n<h2 id=\"store-configuration\">Add to the store configuration<\/h2>\n<p>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.<\/p>\n<p>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.<\/p>\n<p>To add  user  data to an existing store:<\/p>\n<ol>\n<li>\n<p>Make sure you have the <code>id<\/code>of the  user's  store.<br \/>\nTo find that value, you can make a GET  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/get\/stores\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/stores<\/a> request (or a GET  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/get\/merchants\/(merchantId)\/stores\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/merchants\/{merchantId}\/stores<\/a> request).<\/p>\n<\/li>\n<li>\n<p>Make a PATCH  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/patch\/stores\/(storeId)\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/stores\/{storeId}<\/a> request with:<\/p>\n<ul>\n<li>\n<p>A  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/patch\/stores\/(storeId)#request-subMerchantData\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">subMerchantData<\/a> object with the following parameters.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>email<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The email address associated with the  user's  account.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Your unique identifier of your  user. Must be an alphanumerical string with a maximum length of 15 characters.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>mcc<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The 4-digit <a href=\"\/pt\/get-started-with-adyen\/adyen-glossary\/#merchant-category-code\" target=\"_blank\">Merchant Category Code<\/a> of your  user.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>name<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The name of your  user. Based on scheme specifications, this value will overwrite (part of) the <a href=\"\/pt\/account\/transaction-description\/#without-customization\">transaction description<\/a> that will appear on the shopper's bank statement. Must be an alphanumerical string with a maximum length of 22 characters.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n<\/ul>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Add  user  data to an existing store'\" :id=\"'mapi-patch-submerchantdata'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;curl&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/management-test.adyen.com\\\/v3\\\/stores\\\/ST322LJ223223K5F4SQNR9XL5 \\\\\\n-H 'content-type: application\\\/json' \\\\\\n-H 'x-api-key: ADYEN_API_KEY' \\\\\\n-X PATCH \\\\\\n-d '{\\n   \\&quot;subMerchantData\\&quot;:{\\n      \\&quot;email\\&quot;: \\&quot;test-merchant@example.com\\&quot;,\\n      \\&quot;id\\&quot;: \\&quot;12345\\&quot;,\\n      \\&quot;mcc\\&quot;: \\&quot;5734\\&quot;,\\n      \\&quot;name\\&quot;:\\&quot;Test Merchant\\&quot;\\n   }\\n}'&quot;},{&quot;language&quot;:&quot;java&quot;,&quot;tabTitle&quot;:&quot;Java&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Java API Library v39.2.0\\nimport com.adyen.Client;\\nimport com.adyen.enums.Environment;\\nimport com.adyen.model.management.*;\\nimport java.time.OffsetDateTime;\\nimport java.util.*;\\nimport com.adyen.service.management.*;\\n\\nClient client = new Client(\\&quot;ADYEN_API_KEY\\&quot;, Environment.TEST);\\n\\n\\\/\\\/ Create the request object(s)\\nUpdateStoreRequest updateStoreRequest = new UpdateStoreRequest();\\n\\n\\\/\\\/ Send the request\\nAccountStoreLevelApi service = new AccountStoreLevelApi(client);\\nStore response = service.updateStoreById(\\&quot;storeId\\&quot;, updateStoreRequest, null);&quot;},{&quot;language&quot;:&quot;php&quot;,&quot;tabTitle&quot;:&quot;PHP&quot;,&quot;content&quot;:&quot;&lt;?php\\n\\\/\\\/ Adyen PHP API Library v28.1.0\\nuse Adyen\\\\Client;\\nuse Adyen\\\\Environment;\\nuse Adyen\\\\Model\\\\Management\\\\UpdateStoreRequest;\\nuse Adyen\\\\Service\\\\Management\\\\AccountStoreLevelApi;\\n\\n$client = new Client();\\n$client-&gt;setXApiKey(\\&quot;ADYEN_API_KEY\\&quot;);\\n$client-&gt;setEnvironment(Environment::TEST);\\n\\n\\n\\\/\\\/ Create the request object(s)\\n$updateStoreRequest = new UpdateStoreRequest();\\n$updateStoreRequest;\\n\\n\\\/\\\/ Send the request\\n$service = new AccountStoreLevelApi($client);\\n$response = $service-&gt;updateStoreById('storeId', $updateStoreRequest);&quot;},{&quot;language&quot;:&quot;cs&quot;,&quot;tabTitle&quot;:&quot;C#&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen .net API Library v32.0.1\\nusing Adyen;\\nusing Environment = Adyen.Model.Environment;\\nusing Adyen.Model;\\nusing Adyen.Model.Management;\\nusing Adyen.Service.Management;\\n\\nvar config = new Config()\\n{\\n    XApiKey = \\&quot;ADYEN_API_KEY\\&quot;,\\n    Environment = Environment.Test\\n};\\nvar client = new Client(config);\\n\\n\\\/\\\/ Create the request object(s)\\nUpdateStoreRequest updateStoreRequest = new UpdateStoreRequest\\n\\n};\\n\\n\\\/\\\/ Send the request\\nvar service = new AccountStoreLevelService(client);\\nvar response = service.UpdateStoreById(\\&quot;storeId\\&quot;, updateStoreRequest);&quot;},{&quot;language&quot;:&quot;js&quot;,&quot;tabTitle&quot;:&quot;NodeJS (JavaScript)&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Node API Library v28.1.0\\nconst { Client, ManagementAPI } = require('@adyen\\\/api-library');\\n\\nconst client = new Client({ apiKey: \\&quot;ADYEN_API_KEY\\&quot;, environment: \\&quot;TEST\\&quot; });\\n\\n\\\/\\\/ Create the request object(s)\\nconst updateStoreRequest = {\\n  subMerchantData: {\\n    email: \\&quot;test-merchant@example.com\\&quot;,\\n    id: \\&quot;12345\\&quot;,\\n    mcc: \\&quot;5734\\&quot;,\\n    name: \\&quot;Test Merchant\\&quot;\\n  }\\n}\\n\\n\\\/\\\/ Send the request\\nconst managementAPI = new ManagementAPI(client);\\nconst response = managementAPI.AccountStoreLevelApi.updateStoreById(\\&quot;storeId\\&quot;, updateStoreRequest);&quot;},{&quot;language&quot;:&quot;go&quot;,&quot;tabTitle&quot;:&quot;Go&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Go API Library v21.0.0\\nimport (\\n  \\&quot;context\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/common\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/adyen\\&quot;\\n  \\&quot;github.com\\\/adyen\\\/adyen-go-api-library\\\/v21\\\/src\\\/management\\&quot;\\n)\\nclient := adyen.NewClient(&amp;common.Config{\\n  ApiKey:      \\&quot;ADYEN_API_KEY\\&quot;,\\n  Environment: common.TestEnv,\\n})\\n\\n\\\/\\\/ Create the request object(s)\\nupdateStoreRequest := management.UpdateStoreRequest,\\n}\\n\\n\\\/\\\/ Send the request\\nservice := client.Management()\\nreq := service.AccountStoreLevelApi.UpdateStoreByIdInput(\\&quot;storeId\\&quot;).UpdateStoreRequest(updateStoreRequest)\\nres, httpRes, err := service.AccountStoreLevelApi.UpdateStoreById(context.Background(), req)&quot;},{&quot;language&quot;:&quot;py&quot;,&quot;tabTitle&quot;:&quot;Python&quot;,&quot;content&quot;:&quot;# Adyen Python API Library v13.5.1\\nimport Adyen\\n\\nadyen = Adyen.Adyen()\\nadyen.client.xapikey = \\&quot;ADYEN_API_KEY\\&quot;\\nadyen.client.platform = \\&quot;test\\&quot; # The environment to use library in.\\n\\n# Create the request object(s)\\njson_request = {\\n  \\&quot;subMerchantData\\&quot;: {\\n    \\&quot;email\\&quot;: \\&quot;test-merchant@example.com\\&quot;,\\n    \\&quot;id\\&quot;: \\&quot;12345\\&quot;,\\n    \\&quot;mcc\\&quot;: \\&quot;5734\\&quot;,\\n    \\&quot;name\\&quot;: \\&quot;Test Merchant\\&quot;\\n  }\\n}\\n\\n# Send the request\\nresult = adyen.management.account_store_level_api.update_store_by_id(request=json_request, storeId=\\&quot;storeId\\&quot;)&quot;},{&quot;language&quot;:&quot;rb&quot;,&quot;tabTitle&quot;:&quot;Ruby&quot;,&quot;content&quot;:&quot;# Adyen Ruby API Library v10.3.0\\nrequire \\&quot;adyen-ruby-api-library\\&quot;\\n\\nadyen = Adyen::Client.new\\nadyen.api_key = 'ADYEN_API_KEY'\\nadyen.env = :test # Set to \\&quot;live\\&quot; for live environment\\n\\n# Create the request object(s)\\nrequest_body = {\\n  :subMerchantData =&gt; {\\n    :email =&gt; 'test-merchant@example.com',\\n    :id =&gt; '12345',\\n    :mcc =&gt; '5734',\\n    :name =&gt; 'Test Merchant'\\n  }\\n}\\n\\n# Send the request\\nresult = adyen.management.account_store_level_api.update_store_by_id(request_body, 'storeId')&quot;},{&quot;language&quot;:&quot;ts&quot;,&quot;tabTitle&quot;:&quot;NodeJS (TypeScript)&quot;,&quot;content&quot;:&quot;\\\/\\\/ Adyen Node API Library v28.1.0\\nimport { Client, ManagementAPI, Types } from \\&quot;@adyen\\\/api-library\\&quot;;\\n\\nconst client = new Client({ apiKey: \\&quot;ADYEN_API_KEY\\&quot;, environment: \\&quot;TEST\\&quot; });\\n\\n\\\/\\\/ Create the request object(s)\\nconst updateStoreRequest: Types.management.UpdateStoreRequest = \\n};\\n\\n\\\/\\\/ Send the request\\nconst managementAPI = new ManagementAPI(client);\\nconst response = managementAPI.AccountStoreLevelApi.updateStoreById(\\&quot;storeId\\&quot;, updateStoreRequest);&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>You can also make a PATCH request to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/patch\/merchants\/(merchantId)\/stores\/(storeId)\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/merchants\/{merchantId}\/stores\/{storeId}<\/a> endpoint using the same <code>subMerchantData<\/code> object.<\/p>\n<\/li>\n<li>\n<p>In the response note that this contains the full details of the store, including the <code>subMerchantData<\/code> you submitted.<\/p>\n<\/li>\n<\/ol>\n<p>You can also include a  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/post\/stores#request-subMerchantData\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">subMerchantData<\/a> object when you create a new store using a POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/post\/stores\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/stores<\/a> request (or a POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Management\/latest\/post\/merchants\/(merchantId)\/stores\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/merchants\/{merchantId}\/stores<\/a> request).<\/p>\n<h2 id=\"tapi-request\">Add to the Terminal API request<\/h2>\n<p>To add data about your  user  in your Terminal API request:<\/p>\n<ol>\n<li>\n<p>Create an <code>additionalData<\/code> JSON object with the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantId<\/code><\/td>\n<td style=\"text-align: left;\">Your unique identifier of your  user. Must be an alphanumerical string with a maximum length of 19 characters.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantCity<\/code><\/td>\n<td style=\"text-align: left;\">The city of your  user's  address. Must be an alphanumeric string with a maximum length of 13 characters.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantCountry<\/code><\/td>\n<td style=\"text-align: left;\">The three-letter country code in <a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_3166-1_alpha-3\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">ISO 3166-1 alpha-3<\/a> format of your  user's  address. For example, BRA for Brazil.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantName<\/code><\/td>\n<td style=\"text-align: left;\">The name of your  user. Based on scheme specifications, this value will overwrite (part of) the <a href=\"\/pt\/account\/transaction-description\/#without-customization\">transaction description<\/a> that will appear on the shopper's bank statement. Must be an alphanumerical string with a maximum length of 22 characters.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantPostalCode<\/code><\/td>\n<td style=\"text-align: left;\">The postal code of your  user's  address. Maximum length: 8 digits.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantStreet<\/code><\/td>\n<td style=\"text-align: left;\">The street and house number of your  user's address.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantTaxId<\/code><\/td>\n<td style=\"text-align: left;\">The tax ID or your  user.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>subMerchantMcc<\/code><\/td>\n<td style=\"text-align: left;\">The 4-digit <a href=\"\/pt\/get-started-with-adyen\/adyen-glossary\/#merchant-category-code\" target=\"_blank\">Merchant Category Code<\/a> of your  user.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'additionalData JSON object'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"additionalData\\\": {\\n        \\\"subMerchantId\\\": \\\"123456789\\\",\\n        \\\"subMerchantCity\\\": \\\"S\\u00e3o Paulo\\\",\\n        \\\"subMerchantCountry\\\": \\\"BRA\\\",\\n        \\\"subMerchantName\\\": \\\"Empresa XYZ Ltda.\\\",\\n        \\\"subMerchantPostalCode\\\": \\\"04386040\\\",\\n        \\\"subMerchantStreet\\\": \\\"Rua Funcionarios 952\\\",\\n        \\\"subMerchantTaxId\\\": \\\"56861752509\\\",\\n        \\\"subMerchantMcc\\\": \\\"7622\\\"\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Encode the <code>additionalData<\/code> JSON object to Base64. You will pass the resulting string in <code>SaleData.SaleToAcquirerData<\/code>.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Converted to a Base64-encoded string'\" :id=\"''\" :code-data='[{\"language\":\"sh\",\"tabTitle\":\"\",\"content\":\"ewogICAiYWRkaXRpb25hbERhdGEiOnsKICAgICAgInN1Yk1lcmNoYW50SWQiOiIxMjM0NTY3ODkiLAogICAgICAic3ViTWVyY2hhbnRDaXR5IjoiU8OjbyBQYXVsbyIsCiAgICAgICJzdWJNZXJjaGFudENvdW50cnkiOiJCUkEiLAogICAgICAic3ViTWVyY2hhbnROYW1lIjoiRW1wcmVzYSBYWVogTHRkYS4iLAogICAgICAic3ViTWVyY2hhbnRQb3N0YWxDb2RlIjoiMDQzODYwNDAiLAogICAgICAic3ViTWVyY2hhbnRTdHJlZXQiOiJSdWEgRnVuY2lvbmFyaW9zIDk1MiIsCiAgICAgICJzdWJNZXJjaGFudFRheElkIjoiNTY4NjE3NTI1MDkiLAogICAgICAic3ViTWVyY2hhbnRNY2MiOiI3NjIyIgogICB9Cn0=\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p><a href=\"\/pt\/point-of-sale\/basic-tapi-integration\/make-a-payment\">Make a Terminal API payment request<\/a> with the Base64-encoded string as the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/terminal-api\/latest\/post\/payment#request-SaleData-SaleToAcquirerData\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">SaleToAcquirerData<\/a> value.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Add  user  data to a Terminal API request'\" :id=\"'tapi-with-submerchantdata'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"SaleToPOIRequest\\\":{\\n        \\\"MessageHeader\\\":{\\n            \\\"ProtocolVersion\\\":\\\"3.0\\\",\\n            \\\"MessageClass\\\":\\\"Service\\\",\\n            \\\"MessageCategory\\\":\\\"Payment\\\",\\n            \\\"MessageType\\\":\\\"Request\\\",\\n            \\\"SaleID\\\":\\\"POSSystemID12345\\\",\\n            \\\"ServiceID\\\":\\\"0207111104\\\",\\n            \\\"POIID\\\":\\\"V240mPlus-324688179\\\"\\n        },\\n        \\\"PaymentRequest\\\":{\\n            \\\"SaleData\\\":{\\n                \\\"SaleTransactionID\\\":{\\n                    \\\"TransactionID\\\":\\\"27908\\\",\\n                    \\\"TimeStamp\\\":\\\"2025-08-07T10:11:04+00:00\\\"\\n                },\\n                \\\"SaleToAcquirerData\\\": \\\"ewogICAiYWRkaXRpb25hbERhdGEiOnsKIC...ICB9Cn0=\\\"\\n            },\\n            \\\"PaymentTransaction\\\":{\\n                \\\"AmountsReq\\\":{\\n                    \\\"Currency\\\":\\\"BRL\\\",\\n                    \\\"RequestedAmount\\\":120.00\\n                }\\n            }\\n        }\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n<p>Note that the response does not echo the specified  user  data.<\/p>\n<h2>Combining user data and split instructions<\/h2>\n<p>It is possible to provide both user data and <a href=\"\/pt\/platforms\/in-person-payments\/split-transactions\">split instructions<\/a> in the same Terminal API request.<\/p>\n<p>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.<\/p>\n<p>Here is an example:<\/p>\n<ol>\n<li>\n<p>Create an <code>additionalData<\/code> JSON object with the user data and the split instructions.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'JSON object combining data types'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"additionalData\\\": {\\n        \\\"subMerchantId\\\": \\\"123456789\\\",\\n        \\\"subMerchantCity\\\": \\\"S\\u00e3o Paulo\\\",\\n        \\\"subMerchantCountry\\\": \\\"BRA\\\",\\n        \\\"subMerchantName\\\": \\\"Empresa XYZ Ltda.\\\",\\n        \\\"subMerchantPostalCode\\\": \\\"04386040\\\",\\n        \\\"subMerchantStreet\\\": \\\"Rua Funcionarios 952\\\",\\n        \\\"subMerchantTaxId\\\": \\\"56861752509\\\",\\n        \\\"subMerchantMcc\\\": \\\"7622\\\",\\n        \\\"split.api\\\": \\\"1\\\",\\n        \\\"split.nrOfItems\\\": \\\"3\\\",\\n        \\\"split.totalAmount\\\": \\\"8000\\\",\\n        \\\"split.currencyCode\\\": \\\"USD\\\",\\n        \\\"split.item1.amount\\\": \\\"7500\\\",\\n        \\\"split.item1.type\\\": \\\"BalanceAccount\\\",\\n        \\\"split.item1.account\\\": \\\"BA00000000000000000000001\\\",\\n        \\\"split.item1.reference\\\": \\\"Your reference for the sale amount\\\",\\n        \\\"split.item1.description\\\": \\\"Your description for the sale amount\\\",\\n        \\\"split.item2.amount\\\": \\\"500\\\",\\n        \\\"split.item2.type\\\": \\\"Commission\\\",\\n        \\\"split.item2.reference\\\": \\\"Your reference for your commission\\\",\\n        \\\"split.item2.description\\\": \\\"Your description for your commission\\\",\\n        \\\"split.item3.type\\\": \\\"PaymentFee\\\",\\n        \\\"split.item3.account\\\": \\\"BA00000000000000000000001\\\",\\n        \\\"split.item3.reference\\\": \\\"Your reference for the payment fee\\\",\\n        \\\"split.item3.description\\\": \\\"Your description for the payment fee\\\"\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Encode the JSON object to Base64.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Converted to a Base64-encoded string'\" :id=\"''\" :code-data='[{\"language\":\"bash\",\"tabTitle\":\"\",\"content\":\"ewogICAiYWRkaXRpb25hbERhdGEiOnsKICAgICAgInN1Yk1lcmNoYW50SWQiOiIxMjM0NTY3ODkiLAogICAgICAic3ViTWVyY2hhbnRDaXR5IjoiU8OjbyBQYXVsbyIsCiAgICAgICJzdWJNZXJjaGFudENvdW50cnkiOiJCUkEiLAogICAgICAic3ViTWVyY2hhbnROYW1lIjoiRW1wcmVzYSBYWVogTHRkYS4iLAogICAgICAic3ViTWVyY2hhbnRQb3N0YWxDb2RlIjoiMDQzODYwNDAiLAogICAgICAic3ViTWVyY2hhbnRTdHJlZXQiOiJSdWEgRnVuY2lvbmFyaW9zIDk1MiIsCiAgICAgICJzdWJNZXJjaGFudFRheElkIjoiNTY4NjE3NTI1MDkiLAogICAgICAic3ViTWVyY2hhbnRNY2MiOiI3NjIyIiwKICAgICAgInNwbGl0LmFwaSI6IjEiLAogICAgICAic3BsaXQubnJPZkl0ZW1zIjoiMyIsCiAgICAgICJzcGxpdC50b3RhbEFtb3VudCI6IjgwMDAiLAogICAgICAic3BsaXQuY3VycmVuY3lDb2RlIjoiRVVSIiwKICAgICAgInNwbGl0Lml0ZW0xLmFtb3VudCI6Ijc1MDAiLAogICAgICAic3BsaXQuaXRlbTEudHlwZSI6IkJhbGFuY2VBY2NvdW50IiwKICAgICAgInNwbGl0Lml0ZW0xLmFjY291bnQiOiJCQTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIiwKICAgICAgInNwbGl0Lml0ZW0xLnJlZmVyZW5jZSI6IllvdXIgcmVmZXJlbmNlIGZvciB0aGUgc2FsZSBhbW91bnQiLAogICAgICAic3BsaXQuaXRlbTEuZGVzY3JpcHRpb24iOiJZb3VyIGRlc2NyaXB0aW9uIGZvciB0aGUgc2FsZSBhbW91bnQiLAogICAgICAic3BsaXQuaXRlbTIuYW1vdW50IjoiNTAwIiwKICAgICAgInNwbGl0Lml0ZW0yLnR5cGUiOiJDb21taXNzaW9uIiwKICAgICAgInNwbGl0Lml0ZW0yLnJlZmVyZW5jZSI6IllvdXIgcmVmZXJlbmNlIGZvciB5b3VyIGNvbW1pc3Npb24iLAogICAgICAic3BsaXQuaXRlbTIuZGVzY3JpcHRpb24iOiJZb3VyIGRlc2NyaXB0aW9uIGZvciB5b3VyIGNvbW1pc3Npb24iLAogICAgICAic3BsaXQuaXRlbTMudHlwZSI6IlBheW1lbnRGZWUiLAogICAgICAic3BsaXQuaXRlbTMuYWNjb3VudCI6IkJBMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEiLAogICAgICAic3BsaXQuaXRlbTMucmVmZXJlbmNlIjoiWW91ciByZWZlcmVuY2UgZm9yIHRoZSBwYXltZW50IGZlZSIsCiAgICAgICJzcGxpdC5pdGVtMy5kZXNjcmlwdGlvbiI6IllvdXIgZGVzY3JpcHRpb24gZm9yIHRoZSBwYXltZW50IGZlZSIKICAgfQp9\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Pass the Base64-encoded string in the <code>SaleData.SaleToAcquirerData<\/code> parameter of your Terminal API payment request.<\/p>\n<\/li>\n<\/ol>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/platforms\/online-payments\/payment-facilitators\/\"\n                        target=\"_self\"\n                        >\n                    Online payments by payment facilitators\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/pt\/platforms\/in-person-payments\/payment-facilitators","articleFields":{"description":"Learn what additional information you must provide with your transactions if you are a payment facilitator.","feedback_component":true,"type":"page","_expandable":{"operations":""},"status":"current","filters_component":false,"parameters":{"directoryPath":"\/platforms","model":"platform"}},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/platforms\/in-person-payments\/payment-facilitators","title":"Payment facilitators","content":"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 .\nAdyen 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.\nRequirements\n In addition to the general requirements for in-person payments with an Adyen for Platforms integration, take into account the following requirements and limitations. \n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nA Terminal API integration with payment terminals or with a Mobile solution, or a standalone solution.\n\n\nAPI credentials\nTo add  user  data to the store configuration, you must have an API credential that you can use for the  Management API and that has the Management API\u2014Stores read and write role.\n\n\nLimitations\nThe standalone solution only supports adding  user  data through the store configuration.\n\n\n\nMethods to add  user  data\nAdyen automatically adds certain  user  data to transactions  facilitated by your platform. The remaining  user  data must be supplied by you.\nThere are two methods to add  user  data:\n\nThrough the configuration of the store. This is mainly intended for standalone terminals, but can also be used for integrated terminals.\nBy adding fields in the Terminal API requests.\n\nIf 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.\nWhen 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.\nAdd to the store configuration\nIf 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.\nIf 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.\nTo add  user  data to an existing store:\n\n\nMake sure you have the idof the  user's  store.\nTo find that value, you can make a GET  \/stores request (or a GET  \/merchants\/{merchantId}\/stores request).\n\n\nMake a PATCH  \/stores\/{storeId} request with:\n\n\nA  subMerchantData object with the following parameters.\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nemail\n\nThe email address associated with the  user's  account.\n\n\nid\n\nYour unique identifier of your  user. Must be an alphanumerical string with a maximum length of 15 characters.\n\n\nmcc\n\nThe 4-digit Merchant Category Code of your  user.\n\n\nname\n\nThe 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.\n\n\n\n\n\n\n\n\nYou can also make a PATCH request to the  \/merchants\/{merchantId}\/stores\/{storeId} endpoint using the same subMerchantData object.\n\n\nIn the response note that this contains the full details of the store, including the subMerchantData you submitted.\n\n\nYou can also include a  subMerchantData object when you create a new store using a POST  \/stores request (or a POST  \/merchants\/{merchantId}\/stores request).\nAdd to the Terminal API request\nTo add data about your  user  in your Terminal API request:\n\n\nCreate an additionalData JSON object with the following parameters:\n\n\n\nParameter\nDescription\n\n\n\n\nsubMerchantId\nYour unique identifier of your  user. Must be an alphanumerical string with a maximum length of 19 characters.\n\n\nsubMerchantCity\nThe city of your  user's  address. Must be an alphanumeric string with a maximum length of 13 characters.\n\n\nsubMerchantCountry\nThe three-letter country code in ISO 3166-1 alpha-3 format of your  user's  address. For example, BRA for Brazil.\n\n\nsubMerchantName\nThe 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.\n\n\nsubMerchantPostalCode\nThe postal code of your  user's  address. Maximum length: 8 digits.\n\n\nsubMerchantStreet\nThe street and house number of your  user's address.\n\n\nsubMerchantTaxId\nThe tax ID or your  user.\n\n\nsubMerchantMcc\nThe 4-digit Merchant Category Code of your  user.\n\n\n\n\n\n\n\n\nEncode the additionalData JSON object to Base64. You will pass the resulting string in SaleData.SaleToAcquirerData.\n\n\n\n\n\nMake a Terminal API payment request with the Base64-encoded string as the  SaleToAcquirerData value.\n\n\n\n\n\nNote that the response does not echo the specified  user  data.\nCombining user data and split instructions\nIt is possible to provide both user data and split instructions in the same Terminal API request.\nHowever, 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.\nHere is an example:\n\n\nCreate an additionalData JSON object with the user data and the split instructions.\n\n\n\n\n\nEncode the JSON object to Base64.\n\n\n\n\n\nPass the Base64-encoded string in the SaleData.SaleToAcquirerData parameter of your Terminal API payment request.\n\n\nSee also\n\n\n                    Online payments by payment facilitators\n                \n","type":"page","locale":"pt","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Platforms","lvl2":"Process in-person payments","lvl3":"Payment facilitators"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/platforms","lvl2":"https:\/\/docs.adyen.com\/pt\/platforms\/in-person-payments","lvl3":"\/pt\/platforms\/in-person-payments\/payment-facilitators"},"levels":4,"category":"Platforms","category_color":"green","tags":["Payment","facilitators"]}}
