Skip to main content
Embedded Payments

Make a cross-border FX payout

This section describes how digital platforms such as marketplaces, SaaS, e-commerce and fintech companies can use J.P. Morgan Embedded Payments (EP) APIs to convert and settle cross-currency payouts directly into a recipient’s local bank account. The payout is funded from the EP limited or transaction account and delivered to the designated payee (recipient).

Note

For guidance on third-party foreign exchange (FX) cross-border payouts, contact your relationship manager.

Use this section when:

  • The funding account is held in one currency (such as USD) and the payee (recipient) is paid in another currency (such as EUR, GBP, INR) in their local bank account.
  • You want J.P. Morgan to apply the Foreign Exchange (FX) rate and settle the local currency payouts.

Do not use this section when:

  • Both payouts are in the same currency. For more information, see Payouts. 
  • You are moving funds between two of your own EP accounts. For more information, see Initiate transfers.

Before you begin

For limited accounts

  1. Onboard to Embedded Payments and complete client onboarding.
  2. Collect the additional KYC fields required for cross-border payouts from your client.
  3. Real-time market rates and pre-agreed rates are available. Integrate with FX Rate Sheet API, if you want pre-agreed rates. 
  4. Subscribe to webhooks for TRANSACTION_COMPLETED and TRANSACTION_FAILED.
Note

You can make a payout only after you register a payee as type "RECIPIENT" and add a beneficiary bank account in the target currency.

For transaction accounts

  1. Onboard to Embedded Payments with transaction account in funding currency with sufficient balance.
  2. Real-time market rates and pre-agreed rates are available. Integrate with FX Rate Sheet API, if you want pre-agreed rates. 
  3. Subscribe to webhooks for TRANSACTION_COMPLETED and TRANSACTION_FAILED.
Note

You should include an unregistered payee object inline in the payout request for the transaction account.

Sequence diagram

Rail eligibility

In the U.S., wire is used for higher-value FX payouts and ACH is used for lower-value payouts. As the product expands globally, we may add additional payment rails. The following table summarizes the available FX payment rails, their intended use cases and typical settlement timelines.

The following table summarizes the available FX payout rails, their intended use cases, and typical settlement timelines.
Payment rail Use case Settlement period
FX Low-value (e.g. ACH) Non-urgent cross-currency payouts Two to five business days
FX High-value (e.g. Wire) Time-critical cross-currency payouts Same or next business day

Availability

FX payout is available from the New York (NY) branch with USD as the debit currency. The following table lists the supported payout destinations and credit currencies by region, along with the available rails for limited and transaction accounts.

 The following table shows supported regions, markets and credit currencies by payment rail and account type
Regions Countries Credit currencies Limited accounts Transaction accounts
North America (NAMR) 

Canada

 CAD - ACH 
Asia-Pacific (APAC) Australia  AUD Wire, ACH Wire, ACH
Hong Kong  HKD Wire, ACH Wire, ACH
India  INR Wire, ACH Wire, ACH
Philippines  PHP Wire, ACH Wire, ACH
South Korea  KRW Wire Wire
Singapore SGD ACH ACH
Vietnam VDN Wire Wire
Europe, Middle East, and Africa (EMEA) EU EUR Wire Wire
Poland PLN ACH ACH
Romania RON ACH ACH
Sweden SEK - ACH
United Arab Emirates AED ACH ACH
United Kingdom GBP Wire ACH
Latin America (LATAM) Brazil BRL Wire Wire
Mexico MXN Wire Wire

Account eligibility

The following table shows which EP account types support FX payouts and the required beneficiary model:

Account eligibility
Account type  FX payout Beneficiary model
TRANSACTION_ACCOUNT  Supported  Inline payee (creditorPayee) required. No pre-registered recipient needed.

LIMITED_DDA_PAYMENTS 

 Supported, if FX capability is enabled. Registered recipient (creditorRecipientId) required.
LIMITED_DDA  Not supported -
PROCESSING, MANAGEMENT, DEFAULT, OFFSET  Not supported -

How it works

1. Create payee (one-time setup for LIMITED_ACCOUNTS only): Use POST /recipients to create a payee with the target currency specified in account.currencyCode. The payee's currency determines the target for automatic FX conversion. Save the recipientId returned in the response for use in transactions.

Note

If you do not register the payee, you can provide payee details when you submit the request. For more information, see Unregistered recipients.

2. Subscribe to webhooks (one-time setup): Use POST /webhooks to set up webhook subscriptions. Subscribe to transaction events (TRANSACTION_COMPLETED and TRANSACTION_FAILED) to receive status updates with FX details.

3. Obtain rates: Use the FX real-time market rate or Rate Sheet API to retrieve your current rate sheet with pre-agreed exchange rates for supported currencies. The rates are valid for 24 hours. Extract the rateId for your desired currency to lock in the pre-agreed rate.

4. Initiate FX transaction: Use POST /transactions with the recipientId to create a transaction. Specify the amount in USD. The Embedded Payments platform automatically retrieves the current exchange rate for the payee's target currency, applies the FX conversion, and returns both the USD amount and converted target amount with exchange rate details.

5. Receive FX payment details: The transaction response includes, targetAmount (amount the payee receives in their local currency), targetCurrency (payee's currency code) and fxInformation (exchange rate, contract ID, rate ID and spread details) along with standard transaction fields and status.

Implementation

Use the following section to implement each step. It includes prerequisites, required fields and sample API requests and responses.

1. Create payee

For platforms creating registered payee (LIMITED_DDA_PAYMENTS only)

To send FX payouts, you must create payee with the correct currency and country information using the POST /recipients API. The payee's currencyCode and countryCode determine the target currency for FX conversion. Once you create a payee, you can reuse them for multiple transactions, and their currency preferences are automatically applied to all payouts.

In addition to standard payee (recipient) fields, you must include the following FX-specific fields:

  • account.currencyCode: The currency code for FX conversion target currency (for example, "HKD", "GBP"). This is a critical field for enabling FX payouts.
  • account.countryCode: The alpha-2 country code where the bank account is located. (for example, "HK")
  • account.routingInformation: An array of routing objects with routingNumber, transactionType, and routingCodeType.
  • partyDetails.address.countryCode: The country code for payee's physical address.

For FX cross-border payouts, you are required to collect additional Know Your Customer (KYC) information from your clients to process transactions. For more information on the required fields and compliance details, contact us.

2. Subscribe to webhooks

To receive real-time notifications for FX payout events, subscribe to webhooks through the developer portal. Once subscribed, your endpoint receives HTTP POST requests whenever a payout event is triggered, such as payment initiation, status updates or failures. 

Use POST /webhooks to set up webhook subscriptions. For more information, see Notifications. 

Sample response: 

Json
{
  "eventId": "5123",
  "eventType": "TRANSACTION_COMPLETED",
  "resourceType": "TRANSACTIONS",
  "resource": "{\"id\":\"8JJOCLKW3c1sIOp\",\"clientId\": \"1000010400\",\"transactionReferenceId\": \"34jsa668931301jkp\",\"type\":\"ACH\",\"debtorAccountId\":\"d5aaf0db11e747daa2d955806f6eb14e\",\"recipientId\": \"d9dab78e-e366-4dde-ac9d-fb3f9d48437b\",\"amount\":\"20.88\",\"currency\":\"USD\",\"status\":\"COMPLETED\",\"targetAmount\":\"724.38\",\"targetCurrency\":\"INR\",\"fxInformation\":{\"exchangeRate\":\"34.477678\",\"contractId\":\"00490202\",\"rateId\":\"R1C8E57DF6964F981D6DDB5EEf78D8\",\"clientSpread\":\"0.500000\"},\"paymentDate\":\"2024-04-23\",\"ledgerBalance\":\"10.00\"}",
  "resourceObject": {
    "id": "8JJOCLKW3c1sIOp",
    "clientId": "1000010400",
    "transactionReferenceId": "34jsa668931301jkp",
    "type": "ACH",
    "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
    "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
    "amount": "20.88",
    "currency": "USD",
    "status": "COMPLETED",
    "targetAmount": "724.38",
    "targetCurrency": "INR",
    "fxInformation": {
      "exchangeRate": "34.477678",
      "contractId": "00490202",
      "rateId": "R1C8E57DF6964F981D6DDB5EEf78D8",
      "clientSpread": "0.500000"
    },
    "paymentDate": "2024-04-23",
    "ledgerBalance": "10.00"
  }
}

3. Obtain rates

Using FX Ratesheet API 

The FX Ratesheet API is a separate API that provides foreign exchange rates for cross-border payouts. You can use FX Rate Sheet API to retrieve rate sheets with pre-agreed exchange rates, or you can process transactions at real-time market rate.

To use a pre-agreed rate:

  1. Call the FX Rate Sheet API to retrieve your current rate sheet.
  2. Extract the rateId for your currency.
  3. Include the rateId in your transaction request.

For complete API specifications, authentication details, and integration instructions, see the FX Rate Sheet API. 

4. Initiate FX transactions

Payout with a registered payee

Once you have created a payee (recipient) with currency information, you can initiate cross-border payouts using POST /transactions. The system performs currency conversion based on the payee's currencyCode.

There are two options for obtaining an FX rate when initiating a transaction:

  1. Real-time market rates: Omit the rateId field and the transaction processes at the current real-time market rate.
  2. Pre-agreed rates via FX Rate Sheet API: Retrieve a rate sheet, extract the rateId, and include it in your transaction request to lock in a pre-agreed rate. See the FX Rate Sheet API for details.

Sample request (with pre-agreed rate):

Json
{
  "transactionReferenceId": "fxtxn20260110001",
  "amount": 11,
  "currency": "USD",
  "type": "ACH",
  "recipientId": "400e06ed-1745-4051-a1ed-5e4f751b6528",
  "debtorAccountId": "c3a9b877ab4647e6a9eff2cfd7ee6764",
   "targetCurrency": "AUD",
  "memo": "Invoice",
  "fxInformation": {
    "rateId": "R1C8E57DF6964F981D6DDB5EEF78D8"
  }
}

If you do not have a pre-agreed rate or prefer real-time pricing, omit the rateId field and the transaction processes at the current real-time market rate. 

Sample request (with real-time market rate):

Json
{
  "transactionReferenceId": "fxtxn20260110001",
  "amount": 11,
  "currency": "USD",
  "targetCurrency": "AUD",
  "type": "ACH",
  "recipientId": "400e06ed-1745-4051-a1ed-5e4f751b6528",
  "debtorAccountId": "c3a9b877ab4647e6a9eff2cfd7ee6764",
  "memo": "Invoice",
}

Sample response:

Json
{
  "id": "8h1MiAA97hS7vm6",
  "transactionReferenceId": "fxtxn20260110001",
  "status": "PENDING",
  "type": "ACH",
  "debtorAccountId": "c3a9b877ab4647e6a9eff2cfd7ee6764",
  "creditorAccountId": null,
  "amount": 11,
  "currency": "USD",
  "localInstrumentCode": null,
  "createdAt": "2026-06-05T11:40:43Z",
  "targetCurrency": "AUD",
  "targetAmount": null,
  "recipientId": "400e06ed-1745-4051-a1ed-5e4f751b6528",
  "memo": "/PRN/40000000010794",
  "fxInformation": null,
  "debtorName": "EDOARDO FINANCE INTEGRATION",
  "creditorName": "Oil Yc Industry",
  "debtorAccountNumber": "...0794",
  "creditorAccountNumber": "...3456",
  "paymentDate": "2026-01-29"
}

Payout with an unregistered payee

Sample request:

Json
{
  "transactionReferenceId": "fxwire202617",
  "type": "WIRE",
  "memo": "Memo for Transaction EP-POWIRE",
  "currency": "USD",
  "executionDate": "2025-10-31",
  "amount": 1.23,
  "debtor": {
    "account": {
      "type": "REGISTERED_ACCOUNT",
      "registeredAccount": {
        "id": "c3a9b877ab4647e6a9eff2cfd7ee6764"
      }
    }
  },
  "creditor": {
    "id": "3301d211-81ad-4e68-a54e-1c4906312808"
  }
}

Sample response:

Json
{
  "id": "8KDwH10a5WuIgbCf",
  "transactionReferenceId": "fxwire202617",
  "requestedExecutionDate": "2026-01-02"
}

5. Receive FX payment details

After the transaction is processed, use GET /transactions/{transactionId} to retrieve the complete transaction details including FX conversion information.

Sample response:

Json
{
  "transactionReferenceId": "d5205014630d4816a5f3d0013577503e",
  "id": "lQJw2nCKrKBATl8",
  "status": "COMPLETED",
  "type": "ACH",
  "requestedExecutionDate": "2025-12-31",
  "valueDate": "2025-12-31",
  "localInstrumentCode": "PPD",
  "memo": "Memo for Transaction EP-AUD",
  "amount": "9.99",
  "rateId": "R1C8E57DF6964F981D6DDB5EEF78D8",
  "currency": "USD",
  "debtor": {
    "clientId": "1000014199",
    "partyDetails": {
      "name": "ewallet",
      "address": {
        "buildingNumber": "1605",
        "streetName": "Anywhere St",
        "city": "Phoenixville",
        "country": "US",
        "countrySubDivision": "NY",
        "postalCode": "012345"
      }
    },
    "account": {
      "type": "REGISTERED_ACCOUNT",
      "registeredAccount": {
        "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
        "number": "...0794",
        "ledgerBalance": "71178.91",
        "postingVersion": 238
      }
    }
  },
  "creditor": {
    "partyDetails": {
      "name": "ewallet creditor",
      "address": {
        "buildingNumber": "1605",
        "streetName": "Briarwood Ct",
        "city": "Phoenixville",
        "country": "US",
        "countrySubDivision": "NY",
        "postalCode": "19460"
      }
    },
    "account": {
      "type": "CHECKING",
      "externalAccount": {
        "number": "...8800",
        "bankName": "WALLET BANK",
        "routingInformation": [
          {
            "routingNumber": "CHASUS33XXX",
            "transactionType": "ACH",
            "routingCodeType": "BIC"
          }
        ],
        "currency": "USD",
        "country": "US"
      }
    }
  }
}

Reconciliation and reporting

Reconciliation and reporting capabilities are available. To learn more or get started, contact us.