American Express

13 min

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

Set your SE number: on a merchant group, with your payfac name if you're a payfac.

Set your merchant detailsSet your merchant details: trading name, category code, contact detail and addresses, plus a seller ID for your payfac submerchants.

Route Amex cards to Amex Direct: create a routing rule (see Rules GuideRules Guide).

Set merchant details

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"
  }'

Amex field reference and troubleshootingAmex field reference and troubleshooting 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 GuideQuickStart Guide.

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 liveTest and go live.

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:

<KEY> with your API key.

<MERCHANT_ID> 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.

Create a configuration with your SE number

Replace the example values with details from your Amex agreement. If you're not a payfac, leave out payfac_name.

Create a configuration

curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "amex_config": {
      "amex_merchant_id": "<SE_NUMBER>",
      "payfac_name": "Example Payfac"
    }
  }'

Note the id in the response. Later steps call it <AMEX_CONFIGURATION_ID>.

Create a merchant group for your merchants

Create a merchant group

curl -X POST https://mgmt-api.torogateway.dev/v1/merchant-groups \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "external_reference": "Amex merchants",
    "configuration_id": "<AMEX_CONFIGURATION_ID>",
    "parent_group_id": null
  }'

Note the id in the response. Later steps call it <MERCHANT_GROUP_ID>.

Add your merchant to the group

Repeat this for each merchant (or, for payfacs, each submerchant).

Add merchant to merchant group

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

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.

Create a configuration with your merchant details

Replace the example values with your own.

Create configuration with merchant details

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",
    "amex_config": {
      "seller_id": "<SELLER_ID>"
    }
  }'

Note the id in the response. Later steps call it <CONFIGURATION_ID>.

Find your merchant's address

Find merchant's address

curl -X GET https://mgmt-api.torogateway.dev/v1/merchants/<MERCHANT_ID> \
  -H "API-Key: <KEY>"

Note the address_id in the response. Later steps call it <ADDRESS_ID>.

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.

Add the Amex region code to the address

Use the code for the region the business is in.

Add Amex region code

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}}"
  }'

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.

Attach the configuration to your merchant

Attach configuration to 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": "<CONFIGURATION_ID>"
  }'

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.