--- title: American Express slug: american-express docTags: createdAt: 2026-10-09T08:35:30.047Z --- # Accepting American Express Toro has a direct integration with American Express. This section explains how to set it up with the Toro management API. ## How it works Every Amex Direct transaction is sent under an Amex **SE number**, which Amex calls the *Card Acceptor Identification Code *(also known as Merchant ID or SE Number). On Toro, this is `amex_merchant_id`. How you set Toro up depends on how you accept Amex. - **As a merchant with your own SE Number, **for example an enterprise merchant. Your transactions go to Amex under your SE number, wth your trading name (`dba_name`). - **As a payment facilitator (payfac)**, accepting Amex on behalf of other businesses, your **submerchants**. Transactions go to Amex under your SE number, and each one also identifies the submerchant by a **Seller ID** that you assign to it (`seller_id`). | | Merchant with its own SE number | Payfac | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | SE number (`amex_merchant_id`) | On a merchant group configuration, or on the merchant's own configuration if you only have one merchant | On a merchant group configuration for your submerchants | | Payfac name (`payfac_name`) | Not used | On the same merchant group configuration | | Seller ID (`seller_id`) | Not used. Leave it out: setting it makes Toro send the transaction as a payfac transaction | On each submerchant's own configuration | | Name on cardholder statements | `dba_name` | `payfac_name=dba_name` | ## Who sets what | Toro sets this for you | You set this through the API | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Toro's connection to Amex: origin name, Amex region and submitter code | Your SE number (`amex_merchant_id`) | | PIN encryption keys for online PIN | Payfacs only: your payfac name, and a Seller ID (`seller_id`) for each submerchant | | | Trading names (`dba_name`) and merchant category code | | | Contact email and phone number | | | Merchant addresses, including the Amex region code | | | A routing rule that sends Amex cards to Amex Direct | | | Which merchants and terminals use it | ## Setup steps 1. Set your SE number: on a merchant group, with your payfac name if you're a payfac. 2. [Set your merchant details](docId\:P2OxDdAUshA44tg_VpOie): trading name, category code, contact detail and addresses, plus a seller ID for your payfac submerchants. 3. Route Amex cards to Amex Direct: create a routing rule (see [Rules Guide](docId\:zl1hcmoHGYj1rqE01TK-k)). ::::CodeDrawer{title="Set merchant details" isResponseExpanded="true" autoGeneratedAnchorSlug="set-merchant-details" legacyHash="tbThwRLdaPDeTSysFBzKH"} :::CodeblockTabsExamples ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "dba_name": "Example Cabs", "merchant_category_code": "4121", "merchant_email": "payments@example.com", "phone_number": "+441234567890" }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "cfg_abc123", "account_id": "acc_abc123", "dba_name": "Example Cabs", "merchant_category_code": "4121", "merchant_email": "payments@example.com", "phone_number": "+441234567890", "shift4_config": { "id": "acp_abc123", "account_id": "acc_abc123", "acquirer": "shift4", "acquirer_merchant_id": null, "acquirer_submerchant_id": null, "acquirer_terminal_id": null, "acquirer_submerchant_address": null, "supported_card_entry_modes": null, "partial_approval_supported": null, "online_pin_supported": null, "supported_cvms": null, "cvms_supporting_pre_approval": null, "nexo_host_message_to_send": null, "nexo_financial_capture": null, "nexo_completion_exchange_policy": null, "nexo_cancellation_exchange": null, "nexo_card_data_verification": null, "pin_request_supported": null, "acquirer_device_code": null, "immediate_setup_dynamic_terminal": null }, "shift4_amex_config": { "id": "sac_abc123", "account_id": "acc_abc123", "acquirer": "shift4_amex" // ...the same fields as shift4_config, all null }, "amex_config": { "id": "aec_abc123", "account_id": "acc_abc123", "acquirer": "american_express", "amex_merchant_id": null, "payfac_name": null, "seller_id": null, "submitter_code": null, "amex_region": null, "origin_name": null, "nexo_host_message_to_send": null, "nexo_financial_capture": null, "nexo_completion_exchange_policy": null, "nexo_cancellation_exchange": null, "nexo_card_data_verification": null }, "transaction_routing_rule": null, "transaction_routing_rule_id": null, "created_at": "2026-10-09T10:53:38.861144", "updated_at": "2026-10-09T10:53:38.861144" } ``` ::: :::: [Amex field reference and troubleshooting](docId:5Eu1W2dj34srwF1LzQLlb) lists every requirement and the errors you might see. HINT: Before you start, Toro must have connected your account to Amex Direct. We’ll confirm when that’s done. You’ll also need your SE number from American Express. ## What you need - A Toro API key, sent in the `API-Key` header. Its role needs these permissions: - `configurations_public:create`, `configurations_public:read` and `configurations_public: update` - `rules:create`, `rules:read` and `rules:update` - `merchants:read` and `merchants:update` - `merchantgroups:read` and `merchant_groups:update` - `receipts:read` - `accounts:read` - `pois:read` and `pois:update` - A merchant and a terminal (POI) set up as in the [QuickStart Guide](docId\:H3A02hxQIF11S8Rz9fELz). - One test terminal you can run a test Amex card on (for testing). - One production terminal you can run a production Amex card on (for production). - Terminals that have downloaded the latest card configuration from Toro, which includes the American Express applications. See [Test and go live](docId\:yyk-Osvz2pCb-Dow0sS2E). ## Before you start The example responses show the shape of what you'll get back. Your IDs, dates and times will be different. In the requests below, replace: - `` with your API key. - `` with the ID of the merchant you're enabling, e.g. `mer_abc123`. - Any other value in angle brackets with the ID from an earlier step's response. Each step says which. The requests use the sandbox address, `https://mgmt-api.torogateway.dev/v1`. For production, use `https://mgmt-api.torogateway.com/v1` and a production API key. ## Set your SE number Your SE number applies to all the merchants that use it, so you set it once, on a configuration attached to a merchant group. Every merchant you add to the group inherits it. If you're a payfac, your payfac name goes on the same configuration. 1. **Create a configuration with your SE number** :::Paragraph{indent="1"} Replace the example values with details from your Amex agreement. If you're not a payfac, leave out `payfac_name`. ::: ::::CodeDrawer{title="Create a configuration" isResponseExpanded="true" autoGeneratedAnchorSlug="create-a-configuration" legacyHash="y4n3EuNutjG36xT2TbCMq"} :::CodeblockTabsExamples ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "amex_config": { "amex_merchant_id": "", "payfac_name": "Example Payfac" } }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "cfg_amex123", "account_id": "acc_abc123", "dba_name": null, "merchant_category_code": null, "merchant_email": null, "phone_number": null, "shift4_config": { "id": "acp_amex123", "account_id": "acc_abc123", "acquirer": "shift4" // ...the same fields as in "Set your merchant details" step 1, all null }, "shift4_amex_config": { "id": "sac_amex123", "account_id": "acc_abc123", "acquirer": "shift4_amex" // ...the same fields as shift4_config, all null }, "amex_config": { "id": "aec_amex123", "account_id": "acc_abc123", "acquirer": "american_express", "amex_merchant_id": "", "payfac_name": "Example Payfac", "seller_id": null, "submitter_code": null, "amex_region": null, "origin_name": null, "nexo_host_message_to_send": null, "nexo_financial_capture": null, "nexo_completion_exchange_policy": null, "nexo_cancellation_exchange": null, "nexo_card_data_verification": null }, "transaction_routing_rule": null, "transaction_routing_rule_id": null, "created_at": "2026-10-09T10:50:12.104552", "updated_at": "2026-10-09T10:50:12.104552" } ``` ::: :::: Note the `id` in the response. Later steps call it ``. 2. **Create a merchant group for your merchants** ::::CodeDrawer{title="Create a merchant group" isResponseExpanded="true" autoGeneratedAnchorSlug="create-a-merchant-group" legacyHash="BzPxRDjq6mCAfJXPLJQ3b"} :::CodeblockTabsExamples ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/merchant-groups \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "external_reference": "Amex merchants", "configuration_id": "", "parent_group_id": null }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "mgr_abc123", "account_id": "acc_abc123", "external_reference": "Amex merchants", "configuration_id": "cfg_amex123", "parent_group_id": null, "created_at": "2026-10-09T10:51:02.733418", "updated_at": "2026-10-09T10:51:02.733418" } ``` ::: :::: Note the `id` in the response. Later steps call it ``. 3. **Add your merchant to the group** :::Paragraph{indent="1"} Repeat this for each merchant (or, for payfacs, each submerchant). ::: ::::CodeDrawer{title="Add merchant to merchant group" isResponseExpanded="true" autoGeneratedAnchorSlug="add-merchant-to-merchant-group" legacyHash="2OY59_FZifa9FWEmen-uU"} :::CodeblockTabsExamples ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/merchant-groups//merchants \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "merchant_id": "" }' ``` ::: :::CodeblockTabsResponses ```javascript // 204 No Content: the response has no body. ``` ::: :::: HINT: If you only have one merchant, you don't need a merchant group. Put `amex_merchant_id` (and `payfac_name`, if you're a payfac) in the merchant's own configuration in the next section instead. ## Set your merchant details Each submerchant needs its own Seller ID, trading name and contact details, on a configuration attached to that merchant. If you're a payfac, each submerchant also needs its own Seller ID. Toro combines these with the SE number from the merchant group. :::Heading{depth="3" indent="1"} Create a configuration with your merchant details ::: Replace the example values with your own. ::::CodeDrawer{title="Create configuration with merchant details" isResponseExpanded="true" autoGeneratedAnchorSlug="create-configuration-with-merchant-details" legacyHash="PyaWfCSk0nHa7XeH7OmvY"} :::CodeblockTabsExamples ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "dba_name": "Example Cabs", "merchant_category_code": "4121", "merchant_email": "payments@example.com", "phone_number": "+441234567890", "amex_config": { "seller_id": "" } }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "cfg_abc123", "account_id": "acc_abc123", "dba_name": "Example Cabs", "merchant_category_code": "4121", "merchant_email": "payments@example.com", "phone_number": "+441234567890", "shift4_config": { "id": "acp_abc123", "account_id": "acc_abc123", "acquirer": "shift4", "acquirer_merchant_id": null, "acquirer_submerchant_id": null, "acquirer_terminal_id": null, "acquirer_submerchant_address": null, "supported_card_entry_modes": null, "partial_approval_supported": null, "online_pin_supported": null, "supported_cvms": null, "cvms_supporting_pre_approval": null, "nexo_host_message_to_send": null, "nexo_financial_capture": null, "nexo_completion_exchange_policy": null, "nexo_cancellation_exchange": null, "nexo_card_data_verification": null, "pin_request_supported": null, "acquirer_device_code": null, "immediate_setup_dynamic_terminal": null }, "shift4_amex_config": { "id": "sac_abc123", "account_id": "acc_abc123", "acquirer": "shift4_amex" // ...the same fields as shift4_config, all null }, "amex_config": { "id": "aec_abc123", "account_id": "acc_abc123", "acquirer": "american_express", "amex_merchant_id": null, "payfac_name": null, "seller_id": "", "submitter_code": null, "amex_region": null, "origin_name": null, "nexo_host_message_to_send": null, "nexo_financial_capture": null, "nexo_completion_exchange_policy": null, "nexo_cancellation_exchange": null, "nexo_card_data_verification": null }, "transaction_routing_rule": null, "transaction_routing_rule_id": null, "created_at": "2026-10-09T10:53:38.861144", "updated_at": "2026-10-09T10:53:38.861144" } ``` ::: :::: Note the `id` in the response. Later steps call it ``. :::Heading{depth="3" indent="1"} Find your merchant's address ::: ::::CodeDrawer{title="Find merchant's address" isResponseExpanded="true" autoGeneratedAnchorSlug="find-merchants-address" legacyHash="YiTtRJJmaGsMZpT-paXYv"} :::CodeblockTabsExamples ```curl curl -X GET https://mgmt-api.torogateway.dev/v1/merchants/ \ -H "API-Key: " ``` ::: :::CodeblockTabsResponses ```javascript { "id": "mer_abc123", "account_id": "acc_abc123", "external_reference": null, "legal_name": "Example Cabs Ltd", "address_id": "adr_abc123", "is_active": true, "merchant_group_id": null, "configuration_id": null, "created_at": "2026-10-09T10:52:35.388587", "updated_at": "2026-10-09T10:52:35.388587", "address": { "id": "adr_abc123", "account_id": "acc_abc123", "line_1": "1 Example Street", "line_2": null, "line_3": null, "city": "London", "district": null, "postal_code": "EC1A 1AA", "country_code": "GBR", "formatted_address": null, "latitude": null, "longitude": null, "region": null, "country_name": null, "amex_region_code": null, "created_at": "2026-10-09T10:52:35.388587", "updated_at": "2026-10-09T10:52:35.388587" } } ``` ::: :::: Note the `address_id` in the response. Later steps call it ``. Amex needs `line_1`, `city`, `postal_code` and `country_code` on the address. If any of them are `null` in your response, add them in the next step too. :::Heading{depth="3" indent="1"} Add the Amex region code to the address ::: Use the code for the region the business is in. ::::CodeDrawer{title="Add Amex region code" isResponseExpanded="true" autoGeneratedAnchorSlug="add-amex-region-code" legacyHash="C5gbE6iECEJgqku2g4V45"} :::CodeblockTabsExamples ```curl curl -X PATCH https://mgmt-api.torogateway.dev/v1/addresses/ \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "amex_region_code": "{{REGION_CODE}}" }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "adr_abc123", "account_id": "acc_abc123", "line_1": "1 Example Street", "line_2": null, "line_3": null, "city": "London", "district": null, "postal_code": "EC1A 1AA", "country_code": "GBR", "formatted_address": null, "latitude": null, "longitude": null, "region": null, "country_name": null, "amex_region_code": "{{REGION_CODE}}", "created_at": "2026-10-09T10:52:35.388587", "updated_at": "2026-10-09T11:02:10.512301" } ``` ::: :::: A transaction is declined before it reaches Amex if the merchant's address has no `amex_region_code`, `line_1` or `city`. Repeat steps 2 and 3 for every merchant you enable. :::Heading{depth="3" indent="1"} Attach the configuration to your merchant ::: ::::CodeDrawer{title="Attach configuration to merchant" isResponseExpanded="true" autoGeneratedAnchorSlug="attach-configuration-to-merchant" legacyHash="llclE4LIp4_0qV8WPEKeA"} :::CodeblockTabsExamples ```curl curl -X PATCH https://mgmt-api.torogateway.dev/v1/merchants/ \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "configuration_id": "" }' ``` ::: :::CodeblockTabsResponses ```javascript { "id": "mer_abc123", "account_id": "acc_abc123", "external_reference": null, "legal_name": "Example Cabs Ltd", "address_id": "adr_abc123", "is_active": true, "merchant_group_id": null, "configuration_id": "cfg_abc123", "created_at": "2026-10-09T10:52:35.388587", "updated_at": "2026-10-09T11:03:44.208113" // the response also includes the merchant's address, as in step 2 } ``` ::: :::: Attach this configuration to the merchant, not to the merchant group. Each submerchant needs its own configuration, because each has its own `seller_id`. Note: `dba_name`, `merchant_category_code`, `merchant_email` and `phone_number` aren't Amex-only. Your other acquirers use them too, so the values you set here apply to every card brand for this merchant.