Merchant Details

8 min

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.

Create the configuration

curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "dba_name": "Example Cabs",
    "merchant_category_code": "4121",
    "merchant_email": "[email protected]",
    "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.
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

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 -X POST https://mgmt-api.torogateway.dev/v1/addresses \
  -H "Content-Type: application/json" \
  -H "API-Key: <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 -X PATCH https://mgmt-api.torogateway.dev/v1/addresses/<ADDRESS_ID> \
  -H "Content-Type: application/json" \
  -H "API-Key: <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.

Attach the configuration

Attach the configuration to your merchant group:

curl -X PATCH https://mgmt-api.torogateway.dev/v1/merchant-groups/<MERCHANT_GROUP_ID> \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "configuration_id": "cfg_abc123"
  }'

Or to a single merchant:

curl -X PATCH https://mgmt-api.torogateway.dev/v1/merchants/<MERCHANT_ID> \
  -H "Content-Type: application/json" \
  -H "API-Key: <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.

Merchant Details

Set your merchant details

﻿Create the configuration﻿

Add the Amex region code to your addresses

Attach the configuration

Create the configuration