API ReferenceCustomersAPI IntegrationConversions

Request Conversion

Execute a currency exchange based on a quote. This endpoint will execute the exchange of one currency for another in accordance with a previously created Quote. For instance, if you requested a quotation to sell 1000 GBP and buy EUR and then called this endpoint with the `quote_id` (prior to the quote's expiry), then the exchange will be fulfilled. A successful response will contain the `conversion_id` which you can use to check for status updates. **Important Notes:** - The quote must be active and not expired - You can only request one conversion from a quote - Once requested, you should ensure that your wallet balance is sufficient to fund this conversion - If you don't send funds within 24 hours, your transfer may be delayed, and you may incur additional charges as per our terms and conditions **Authentication:** [Bearer token required](/api-guide/getting-started/authentication#oauth-20-authentication)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

customer_idstringRequired
Unique Customer Identifier

Query parameters

client_reference_idstringOptional<=36 characters
Unique reference ID that you want to assign to this conversion for your own purposes. Maximum length is 36 characters.

Request

This endpoint expects an object.
quote_idstringRequiredformat: "uuid"
ID of Quote to be used as the basis for the Conversion. This must be a valid quote ID from a previously created quote (see [Create Quote](/api-reference/customers/api-integration/quotes/create-quote)). **Important:** - The quote must be active and not expired - You can only request one conversion from a quote - Once a quote is used for a conversion, it cannot be used again

Response

Ok. The forex conversion request was successful. Note: If you don’t send funds within 24 hours, your transfer may be delayed, and you may incur additional charges as per our terms and conditions.

conversion_idstring

ID of this currency exchange for future reference. Use this ID to check the status of the conversion or retrieve conversion details via the Get a Conversion endpoint.

instruction_numberstring

Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}.

This instruction number can be used to track and reference the conversion in your system.

selling_currencystring
ISO Code for the currency being sold. This is the source currency you are exchanging from. **Format:** 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g., GBP, USD, EUR)
buying_currencystring
ISO Code for the currency being bought. This is the destination currency you are exchanging to. **Format:** 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g., GBP, USD, EUR)
selling_amountdouble

Amount of the currency being sold. This represents the source currency amount that will be exchanged.

Format: Decimal number with up to 2 decimal places Precision: Maximum 2 decimal places

buying_amountdouble

Amount of the currency being bought. This represents the destination currency amount you will receive.

Format: Decimal number with up to 2 decimal places Precision: Maximum 2 decimal places

agreed_ratedouble
Exchange rate agreed upon for this conversion. This rate determines how much of the buying currency will be received for each unit of the selling currency. **Calculation:** `buying_amount = selling_amount × agreed_rate` **Note:** This rate is locked in at the time of booking and will be used for the conversion execution.
booking_datetimedatetime

Timestamp of this request/deal. This is the date and time when the conversion was booked and the exchange rate was locked in.

Format: ISO 8601 date-time format (YYYY-MM-DDTHH:MM:SSZ)

status"OPEN"
Status of this conversion transaction. For newly created conversions, the status will always be "OPEN", indicating that the FX conversion is active and available for use. The agreed FX rate and conversion details are still valid, and the conversion can be used to process payments or settlements.
value_datestringformat: "date"
This is the estimated date for the delivery of the funds into your wallet or (if making an outbound Payment) the Recipient's Bank Account. It is dependent upon a few conditions, such as: - The time of day of the request - Whether there is sufficient cleared funds in your account - The currency - The payment processing route to the bank account **Format:** ISO 8601 date format (YYYY-MM-DD)

Errors