--- title: Merchant Details slug: merchant-details docTags: createdAt: 2026-10-09T09:08:23.504Z --- ## Set your merchant details Every Amex Direct transaction describes the business taking the payment. Amex uses these details to work out which payfac and submerchant the payment belongs to, to show the right name on the cardholder's statement, and to contact the business if a payment is questioned. | What Amex needs | Toro field | Where it's set | | ---------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | | The payfac's SE number | `amex_merchant_id` | The payfac's merchant group configuration | | The payfac's name | `payfac_name` | The payfac's merchant group configuration | | The submerchant's Seller ID | `seller_id` | The submerchant's configuration | | Trading name | `dba_name` | The submerchant's configuration | | Merchant category code (MCC) | `merchant_category_code` | A configuration | | Contact email | `merchant_email` | A configuration. Required for every submerchant. | | Contact phone number | `phone_number` | A configuration. Amex gets the phone number if one is set, and the email if not. | | Street, city and postcode | `line_1`, `city`, `postal_code` | The merchant's address | | Region | `amex_region_code` | The merchant's address | | Country | `country_code` | The merchant's address | | Terminal ID | Derived from the POI ID | Toro, automatically | | Toro's connection to Amex (origin, region, submitter code) | `origin_name`, `amex_region`, `submitter_code` | Toro, on your account's default configuration | The card and payment details (amount, card data, how the card was read) come from the terminal with each transaction. If any of the required details are missing, Toro declines the transaction before it reaches Amex. :::Heading{depth="3" indent="1"} Create the configuration ::: ```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" }' ``` | Field | Required for Amex | Notes | | ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `dba_name` | Yes | Your trading name, which appears on the cardholder's statement. See [Trading name length](#trading-name-length). | | `merchant_category_code` | Yes | Your 4-digit ISO 18245 MCC, for example `4121` for taxis. Use the MCC agreed with Toro. | | `merchant_email` | Yes | Amex requires an email address for every seller under a payfac. | | `phone_number` | Recommended | E.164 format, for example `+441234567890`. Amex uses the phone number as your contact detail if you set one, and the email if not. | The response includes the new configuration's `id` (for example `conf_abc123`). You'll use it in step 3. **Trading name length** The name Amex shows on the cardholder's statement depends on whether the merchant is a payfac's submerchant or a merchant with its own SE number. Toro treats a merchant as a submerchant when its configuration has a `seller_id`. | Merchant type | Name sent to Amex | Longest `dba_name` | | ------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------- | | Merchant with its own SE number (no `seller_id`) | `dba_name`, for example `Example Cabs` | 38 characters | | Payfac submerchant (has a `seller_id`) | `payfac_name=dba_name`, for example `CabCard=Example Cabs` | 37 characters minus the length of `payfac_name` | The whole name is cut off after 38 characters, so a longer `dba_name` is shortened on cardholder statements If a field is missing, Toro uses a fallback: - No `dba_name`: a merchant with its own SE number is shown as its SE number (`amex_merchant_id`), and a submerchant is shown as its `seller_id` after the `=`. - No `payfac_name`: the payfac's SE number is used before the `=`. Set `dba_name`, and for payfacs `payfac_name`, so cardholders see a name they re :::Heading{depth="3" indent="1"} Add the Amex region code to your addresses ::: Amex receives the merchant's address on each transaction, and needs a region code as part of it. Toro takes the address from the merchant record (`address_id`). Set `amex_region_code` on every merchant address, using the codes from Amex's Global Codes list, found in the American Express Global Codes & Information Guide. For the UK, see UK region codes. To create a new address: ```curl curl -X POST https://mgmt-api.torogateway.dev/v1/addresses \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "line_1": "1 Example Street", "city": "Falmouth", "postal_code": "TR11 1AA", "amex_region_code": "{{REGION_CODE}}", "country_code": "GBR" }' ``` To update an existing address: ```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}}" }' ``` | Field | Required for Amex | Notes | | ------------------ | ----------------- | --------------------------------------------------------- | | `line_1` | Yes | Street address. | | `city` | Yes | | | `postal_code` | Yes | | | `amex_region_code` | Yes | 2–3 uppercase characters from the Amex Global Codes list. | | `country_code` | Yes | ISO 3166 alpha-3, for example `GBR`. | HINT: A transaction with a missing `amex_region_code` or `line_1` is declined by the Toro gateway before it reaches Amex. Check every merchant you plan to enable. :::Heading{depth="3" indent="1"} Attach the configuration ::: Attach the configuration to your merchant group: ```curl curl -X PATCH https://mgmt-api.torogateway.dev/v1/merchant-groups/ \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "configuration_id": "cfg_abc123" }' ``` Or to a single merchant: ```curl curl -X PATCH https://mgmt-api.torogateway.dev/v1/merchants/ \ -H "Content-Type: application/json" \ -H "API-Key: " \ -d '{ "configuration_id": "cfg_abc123" }' ``` HINT: `dba_name`, `merchant_category_code`, `merchant_email` and `phone_number` aren't Amex-only. Your other acquirers use them too. The values you set here apply to every card brand, for all merchants and temrinals below that level that don't set their own. Amex cards keep going to your current acquirer until you route them to Amex Direct.