Forward payments

These endpoints help your application create and fund a forward FX contract. A forward contract lets you agree an exchange rate today for exchanging one currency for another on a future date. This can make your customer’s future payment more predictable by reducing the impact of currency-rate changes. The flow is: request a quote, review or update the details, create the contract to lock the rate, use the invoice to fund it, and then attach payment instructions.

API Endpoints

For a reliable integration, save the quoteId returned by the quote endpoints and the contractNumber returned when the contract is created. You will need these identifiers for later requests. In FX terminology, the sell currency is the currency sent to XE, and the buy currency is the currency received by the recipient. The value date is the date the currencies are scheduled to settle.

Create a Forward Quote

Returns an indicative forward rate, fees and total transfer cost for the currency pair, amount, settlement method, delivery method and value date you provide. Use the response to show your customer what they will send, what the recipient is expected to receive and what the transfer will cost. You can also include payments and recipients in the quote. The quote is valid for 60 seconds from the response timestamp.

POST /v2/fxquotes

Update Quote Details

Updates an existing forward quote when your application changes inputs such as the amount, settlement method, delivery method, payments or recipients. The response contains a new indicative rate, fees and total transfer cost for those parameters. The updated quote is valid for 60 seconds from the response timestamp. Create the FX contract with the returned quoteId before it expires to lock in the rate.

PATCH /v2/fxquotes/{quoteId}

Refresh Quote

Refreshes an expiring quote and returns an updated indicative rate. Use this when a customer needs more time to review the quote or when your application cannot create the contract before the current quote expires. Create the FX contract with the refreshed quoteId before it expires to lock in the rate.

POST /v2/fxquotes/{quoteId}/refresh

Create FX Contract

Creates the forward FX contract from the quote. This locks in the agreed rate and terms for the future value date, rather than returning another quote. The response includes the contract number you will use for follow-up requests. After the contract is created, download its invoice to get the instructions for funding it.

POST /v2/contracts/quote/{quoteId}

Download Invoice

Downloads the invoice for the FX contract. The invoice contains the payment details your application or customer needs to send the sell currency to XE and fund the contract. XE also emails the invoice to your registered email address.

GET /v2/contracts/{contractNumber}/invoice

Attach Payment Instructions

Adds one or more registered recipients to the approved contract and records the purpose of the payment. Use this after the contract has been created and funded. Each recipient’s currency must match the contract’s buy currency, and the total disbursement cannot exceed the contract’s buy amount.

POST /v2/contracts/{contractNumber}/payments

Sequence diagram

This diagram shows the recommended request sequence for a software integration: obtain a quote, create the contract before the quote expires, fund the contract using the invoice, and provide payment instructions.

Process flow

This flow is a practical guide for implementing the lifecycle in your application. Persist the quote and contract identifiers, handle quote expiry, and wait for funding before sending payment instructions.