> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.redpincompany.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server. # Request Conversion POST https://sandbox.currenciesdirect.com/v1/customers/{customer_id}/conversions Content-Type: application/json 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) Reference: https://docs.redpincompany.com/api-reference/customers/api-integration/conversions/request-conversion ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the [Authentication](/api-guide/getting-started/authentication#oauth-20-authentication) section for detailed information on how to obtain and use your OAuth credentials. ## Servers - `https://sandbox.currenciesdirect.com` (Sandbox, default) - `https://api.redpincompany.com` (Production) ## Request ### Path parameters - `customer_id` (string, required) — Unique Customer Identifier ### Query parameters - `client_reference_id` (string, optional) — Unique reference ID that you want to assign to this conversion for your own purposes. Maximum length is 36 characters. ### Body (application/json) This endpoint expects a RequestConversionRequest. - `quote_id` (string, required) — 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 ### 200 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_id` (string, required) — 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](/api-reference/customers/api-integration/conversions/get-conversion#request.path.conversion_id) endpoint. - `instruction_number` (string, required) — 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_currency` (string, required) — 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_currency` (string, required) — 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_amount` (double, required) — 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_amount` (double, required) — 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_rate` (double, required) — 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_datetime` (datetime, required) — 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` (enum, required) — 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: `OPEN` - `value_date` (date, required) — 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 Bad request - validation errors or invalid parameters - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ### 401 Unauthorized Error Unauthorized - invalid authorization header - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ### 404 Not Found Error Quote not found or customer not found - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ### 500 Internal Server Error Internal server error or quote expired - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ## Examples **Request** ```json { "quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375" } ``` **Response** ```json { "conversion_id": "2907898", "instruction_number": "0202000005923566-000000011", "selling_currency": "GBP", "buying_currency": "EUR", "selling_amount": 9.25, "buying_amount": 43, "agreed_rate": 4.6474, "booking_datetime": "2018-10-19T10:51:13Z", "status": "OPEN", "value_date": "2018-10-19" } ``` **SDK Code** ```shell cURL curl -X POST https://api.redpincompany.com/v1/customers/{customerId}/conversions \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {access-token}' \ -d '{ "quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375" }' ``` ```python Standard Conversion Request import requests url = "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions" querystring = {"client_reference_id":"CONV-2024-001"} payload = { "quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript Standard Conversion Request const url = 'https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"quote_id":"42a8a4e6-05e0-4188-bd87-70a2febb5375"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Standard Conversion Request package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001" payload := strings.NewReader("{\n \"quote_id\": \"42a8a4e6-05e0-4188-bd87-70a2febb5375\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Standard Conversion Request require 'uri' require 'net/http' url = URI("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"quote_id\": \"42a8a4e6-05e0-4188-bd87-70a2febb5375\"\n}" response = http.request(request) puts response.read_body ``` ```java Standard Conversion Request import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"quote_id\": \"42a8a4e6-05e0-4188-bd87-70a2febb5375\"\n}") .asString(); ``` ```php Standard Conversion Request request('POST', 'https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001', [ 'body' => '{ "quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Standard Conversion Request using RestSharp; var client = new RestClient("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"quote_id\": \"42a8a4e6-05e0-4188-bd87-70a2febb5375\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Standard Conversion Request import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/conversions?client_reference_id=CONV-2024-001")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```