Execute a conversion (consume a quote)

POST

conversions

curl --request POST \
  --url https://api.example.com/v1/conversions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quoteId": "550e8400-e29b-41d4-a716-446655440000"
}
'

import requests

url = "https://api.example.com/v1/conversions"

payload = { "quoteId": "550e8400-e29b-41d4-a716-446655440000" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({quoteId: '550e8400-e29b-41d4-a716-446655440000'})
};

fetch('https://api.example.com/v1/conversions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/conversions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'quoteId' => '550e8400-e29b-41d4-a716-446655440000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/conversions"

	payload := strings.NewReader("{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/conversions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/conversions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "<string>",
  "fee": "0.0000",
  "feeCurrency": "USD",
  "id": "uuid",
  "rate": "1.09860000",
  "sourceAmount": "500.0000",
  "sourceCurrency": "USD",
  "status": "completed",
  "targetAmount": "455.1200",
  "targetCurrency": "EUR",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Headers

Idempotency-Key

string

A repeat returns the original conversion result.

Zuba-Account-Id

string<uuid>

Optional. Names an owned sub-account (UUID) to convert as: the conversion debits and credits that sub-account's own balance, never the master's, and only a quote minted with the same Zuba-Account-Id can be spent (any other quote returns 400 QUOTE_NOT_FOUND). A sub-account that is not active returns 422 ACCOUNT_NOT_ACTIVE. Omit to convert on the master (tenant) balance, spending any quote of the master and its sub-accounts. Naming an account this key does not own returns 403 not_account_owner.

Body

application/json

quoteId

string

required

Id of the firm convert quote to execute

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

The executed conversion: completed, or pending while the institution holding both sides of the pair executes it, after which it reads completed, or failed with the source debit returned to the source balance.

createdAt

string

required

Created at (ISO 8601)

fee

string

required

Per-conversion fee charged on the source leg, in feeCurrency, as locked on the quote: the greater of the basis-point charge and the fixed floor from your pricing, "0.0000" when your pricing carries none. Part of the source amount, not added to it.

Example:

"0.0000"

feeCurrency

string

required

Fee currency

Example:

"USD"

string

required

Conversion id

Example:

"uuid"

rate

string

required

All-in rate applied: source units per 1 target unit

Example:

"1.09860000"

sourceAmount

string

required

Debited from the source balance

Example:

"500.0000"

sourceCurrency

string

required

Source currency

Example:

"USD"

status

enum<string>

required

pending while the conversion is in flight, with the source amount already debited; completed once the target amount is credited; failed when nothing was converted and the source amount is back on the source balance

Available options:

completed,

failed,

pending

Example:

"completed"

targetAmount

string

required

Credited to the target balance

Example:

"455.1200"

targetCurrency

string

required

Target currency

Example:

"EUR"

accountId

string<uuid>

Owning sub-account; present when the conversion was made in a sub-account context (Zuba-Account-Id header) and booked on that sub-account's balance. Absent = the conversion booked on your master account.

Execute a conversion (consume a quote)

curl --request POST \
  --url https://api.example.com/v1/conversions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quoteId": "550e8400-e29b-41d4-a716-446655440000"
}
'

import requests

url = "https://api.example.com/v1/conversions"

payload = { "quoteId": "550e8400-e29b-41d4-a716-446655440000" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({quoteId: '550e8400-e29b-41d4-a716-446655440000'})
};

fetch('https://api.example.com/v1/conversions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/conversions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'quoteId' => '550e8400-e29b-41d4-a716-446655440000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/conversions"

	payload := strings.NewReader("{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/conversions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/conversions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quoteId\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "<string>",
  "fee": "0.0000",
  "feeCurrency": "USD",
  "id": "uuid",
  "rate": "1.09860000",
  "sourceAmount": "500.0000",
  "sourceCurrency": "USD",
  "status": "completed",
  "targetAmount": "455.1200",
  "targetCurrency": "EUR",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}