> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Amex

> Obtain American Express SFTP credentials and encryption keys, then connect Amex as a data source for settlement and payout data.

This guide will help you obtain SFTP credentials and encryption keys and connect American Express (AMEX) as a data source in Payrails to ingest settlement and payout data. With the self-serve flow you configure the integration yourself in the Payrails portal.

## Prerequisites

You will need:

* An active American Express Merchant Account
* **SFTP Access:** A dedicated SFTP username and password assigned to your merchant account
* **PGP Encryption:** A PGP key pair (you must hold the Private Key) for file decryption

## Step-by-step instructions

### Step 1: Gather SFTP Credentials and Connection Details

To configure the secure file transfer, you will need to gather the following information:

**1. SFTP host and port**

Gather the following credentials:

* **Host:** `fsgateway.americanexpress.com`
* **Username:** the AMEX SFTP username assigned to your merchant account (e.g. `PAYRAILS...`)
* **Password:** the password associated with this SFTP user
* **Port:** confirm standard port **22** is used

**PGP decryption**

* **PGP Private Key:** the full PEM-encoded private key block to decrypt the files
* **Passphrase:** *(optional)* if the private key is password-protected

**2. Verify data lifecycle & storage**

Before integrating, confirm the file lifecycle logic on your AMEX SFTP server to ensure consistent data retrieval and support for backfills:

* **Folder structure:** confirm that new reports land in the `/outbox/` directory and are automatically moved to `/sent/` after download.
* **Inbox retention:** verify how long files remain in `/outbox/` if not picked up (standard is typically 7 days).
* **Archive retention:** verify how long files persist in `/sent/` before permanent deletion (standard is typically 24 hours).
* **Backfill availability:** determine if older files are available in `/sent/` or a separate archive path for re-ingestion.

***

### Step 2: Add the Amex integration in the Payrails portal (self-serve)

1. Log in to the Payrails portal and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In **New integration instance**.
4. On **Select provider**, choose **American Express** and click **Continue**.
5. On the **Configure account** screen, fill in:
   * **Integration instance name** — a unique label.
   * **Start Date** — the date of today or tomorrow (currently backfilling data is not available over the self-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * **SFTP host** — `fsgateway.americanexpress.com`
   * **SFTP username** and **password**
   * **Port** — `22`
   * **PGP private key** and, if applicable, the **passphrase**
   * *(Optional)* **Additional data**.
6. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.


## Related topics

- [Amex](/docs/orchestration/integrations/amex.md)
- [Conditions and Branching](/docs/orchestration/workflow-studio/conditions/index.md)
- [Provider Routing with Conditions](/docs/orchestration/workflow-studio/examples/provider-routing.md)