# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 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). > 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](/docs/embedded-finance-solutions/embedded-payments/capabilities/transactions/payouts/overview). - You are moving funds between two of your own EP accounts. For more information, see [Initiate transfers](/docs/embedded-finance-solutions/embedded-payments/capabilities/transactions/fund-account/how-to/initiate-transfers). ## Before you begin **For limited accounts** 1. Onboard to [Embedded Payments](/docs/embedded-finance-solutions/embedded-payments/index) 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](/docs/treasury/fx-rate-sheet/doc) API, if you want pre-agreed rates. 4. Subscribe to webhooks for TRANSACTION_COMPLETED and TRANSACTION_FAILED. > 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](/docs/embedded-finance-solutions/embedded-payments/index) 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](/docs/treasury/fx-rate-sheet/doc) API, if you want pre-agreed rates. 3. Subscribe to webhooks for TRANSACTION_COMPLETED and TRANSACTION_FAILED. > 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 | Wire | Wire, 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) | European Union (EU) | EUR | Wire | Wire | | Poland | PLN | ACH | ACH | | Romania | RON | ACH | ACH | | Sweden | SEK | - | ACH | | United Arab Emirates (UAE) | AED | ACH | ACH | | United Kingdom (UK) | GBP | Wire | ACH | | Latin America (LATAM) | Brazil | BRL | Wire | Wire | | Mexico | MXN | Wire | Wire | > Decimals are not supported. You must enter whole numbers for KRW, JPY, VND, CLP and PYG credit currencies. > > Minimum amount thresholds: > > > - Philippine peso (PHP): Wire: USD 1,000 and ACH: USD 75 > > - Japanese yen (JPY): USD 3,000 > > - Australian dollar (AUD): USD 6 > > - Hong Kong dollar (HKD): USD 100 > ## 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 /recipient`s 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. > If you do not register the payee, you can provide payee details when you submit the request. For more information, see [Unregistered recipients](/docs/embedded-finance-solutions/embedded-payments/capabilities/transactions/payouts/overview#registered-and-unregistered-payment-party). > **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](/docs/embedded-finance-solutions/embedded-payments/capabilities/notification-subscriptions/index). 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](/docs/treasury/fx-rate-sheet/doc) 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](/docs/treasury/fx-rate-sheet/doc) 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](/docs/treasury/fx-rate-sheet/doc) API for details. Sample request (with pre-agreed rate): ```json { "transactionReferenceId": "fxtxn20260110001", "amount": 11, "currency": "USD", "type": "WIRE", "recipientId": "400e06ed-1745-4051-a1ed-5e4f751b6528", "debtorAccountId": "c3a9b877ab4647e6a9eff2cfd7ee6764", "targetCurrency": "BRL", "memo": "Invoice", "fxInformation": { "rateId": "R1C8E57DF6964F981D6DDB5EEF78D8", "purposeCode": "SUPP" } } ``` 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": "POFXWIREMXN12022026", "type": "WIRE", "memo": "Salary Payments", "currency": "USD", "targetAmount": "123.11", "targetCurrency": "SGD", "paymentPurpose": { "code": "SALA" }, "debtor": { "account": { "type": "REGISTERED_ACCOUNT", "registeredAccount": { "id": "d3371713f14e423f82065c9486ebe15b" } } }, "creditor": { "partyDetails": { "type": "ORGANIZATION", "businessName": "Lion City Solutions Pte Ltd", "address": { "type": "BUSINESS_ADDRESS", "buildingNumber": "10", "streetName": "Raffles Place", "city": "Singapore", "country": "SG", "countrySubDivision": "SG", "postalCode": "048575" }, "contacts": { "phoneNumber": "+65-68484517" } }, "account": { "type": "CHECKING", "externalAccount": { "number": "1234567891", "bankName": "DBS Bank", "routingInformation": [ { "routingNumber": "DBSSSGSG", "transactionType": "WIRE", "routingCodeType": "BIC" } ], "currency": "SGD", "country": "SG" } } } } ``` 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](https://developer.payments.jpmorgan.com/contact) us.