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

OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the Authentication section for detailed information on how to obtain and use your OAuth credentials.

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).

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 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 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)

statusenum
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.
Allowed values:
value_datedate

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

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
500
Internal Server Error