Post
/conversions
Our Create Conversion APIs allow you to execute a conversion between two different currency balances
Security
HTTP
Type basic
Header parameters
api-version
stringRequired
The version of the API. Value: "2025-06-06"
Body parameters
Create Conversion Example
Create Conversion IDR to USD
{
"reference_id": "5296b95d-5cd1-4dd9-84f6-12cffd9682e1",
"quote_id": "qo-bf27b6f2-2e8f-4c12-a301-99b4738fd6f2"
}object
quote_id
string Required
Quote ID in format 'qo-
Pattern^qo-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Exampleqo-123e4567-e89b-12d3-a456-426614174000
reference_id
string Required
ExampleREF123456789
Responses
200
The request has succeeded.
Create Conversion Example
Create Conversion IDR to USD
{
"conversion_id": "cnv-ded92b17-fd82-4951-898f-d88c4267436f",
"quote_id": "qo-b3b7b4da-75d3-4367-b69f-ddd92b368a09",
"reference_id": "5296b95d-5cd1-4dd9-84f6-12cffd9682e1",
"source_amount": 100000,
"source_currency": "IDR",
"destination_amount": 626,
"destination_currency": "USD",
"fx_rate": 6.3E-05,
"status": "PENDING",
"created": "2025-06-02T16:07:21.457Z",
"updated": "2025-06-02T16:07:21.457Z"
}object
conversion_id
string
Conversion ID in format 'cnv-
Pattern^cnv-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Examplecnv-123e4567-e89b-12d3-a456-426614174000
quote_id
string
Quote ID in format 'qo-
Pattern^qo-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Exampleqo-123e4567-e89b-12d3-a456-426614174000
reference_id
string
ExampleREF123456789
source_amount
number
Example1000.0
source_currency
string
Valid values[
"USD",
"SGD",
"IDR",
"PHP",
"MYR",
"THB",
"VND",
"HKD",
"MXN",
"CNY",
"KRW",
"AUD",
"EUR"
]
destination_amount
number
Example14650000.0
destination_currency
string
Valid values[
"USD",
"SGD",
"IDR",
"PHP",
"MYR",
"THB",
"VND",
"HKD",
"MXN",
"CNY",
"KRW",
"AUD",
"EUR"
]
fx_rate
number (float)
Example6.5E-05
status
string
Valid values[
"PENDING",
"SUCCEEDED",
"FAILED"
]
created
string (date-time)
Example2024-03-20T08:30:00Z
updated
string (date-time)
Example2024-03-20T08:30:00Z
failure_code
string
Valid values[
"INSUFFICIENT_BALANCE"
]
ExampleINSUFFICIENT_BALANCE
400
Bad request
Create Conversion Example
Quote Expired
{
"error_code": "QUOTE_EXPIRED",
"message": "The Quote ID qo-bf27b6f2-2e8f-4c12-a301-99b4738fd6f2 has expired. Please retry with a valid Quote ID.",
"http_status": 400
}OneOf
Payouts_v3_Http400ApiValidationError
object (Payouts_v3_Http400ApiValidationError)
error_code
string
Valid values[
"API_VALIDATION_ERROR"
]
message
string
Valid values[
"Inputs are failing validation. The errors field contains details about which fields are violating validation."
]
Payouts_v3_Http400ApiValidationError_BothAmounts
object (Payouts_v3_Http400ApiValidationError_BothAmounts)
error_code
string
Valid values[
"API_VALIDATION_ERROR"
]
message
string
Valid values[
"Both source and destination amounts were specified. Please input only one of these amounts."
]
Payouts_v3_Http400InvalidValueError_UnsupportedSourceCurrency
object (Payouts_v3_Http400InvalidValueError_UnsupportedSourceCurrency)
error_code
string
Valid values[
"INVALID_VALUE_ERROR"
]
message
string
Valid values[
"The source currency specified in the request is not supported. Please check our documentation for currencies available."
]
Payouts_v3_Http400InvalidValueError_UnsupportedDestinationCurrency
object (Payouts_v3_Http400InvalidValueError_UnsupportedDestinationCurrency)
error_code
string
Valid values[
"INVALID_VALUE_ERROR"
]
message
string
Valid values[
"The destination currency specified in the request is not supported. Please check our documentation for currencies available."
]
Payouts_v3_Http400InvalidValueError_AmountTooLow
object (Payouts_v3_Http400InvalidValueError_AmountTooLow)
error_code
string
Valid values[
"INVALID_VALUE_ERROR"
]
message
string
Valid values[
"The transfer amount requested is lower than the prescribed minimum for the region. Amend the transfer amount before retrying."
]
Payouts_v3_Http400InvalidValueError_AmountTooHigh
object (Payouts_v3_Http400InvalidValueError_AmountTooHigh)
error_code
string
Valid values[
"INVALID_VALUE_ERROR"
]
message
string
Valid values[
"The transfer amount requested is higher than the prescribed maximum for the region. Amend the transfer amount before retrying."
]
Payouts_v3_Http400InvalidQuote
object (Payouts_v3_Http400InvalidQuote)
error_code
string
Valid values[
"INVALID_QUOTE"
]
message
string
Valid values[
"This quote was created for a different transaction type. Please create a new Quote with the correct transaction type."
]
401
Unauthorized
object
error_code
string
Valid values[
"INVALID_API_KEY"
]
message
string
Valid values[
"API key format is invalid"
]
403
Forbidden
OneOf
Payouts_v3_Http403RequestForbiddenError
object (Payouts_v3_Http403RequestForbiddenError)
error_code
string
Valid values[
"REQUEST_FORBIDDEN_ERROR"
]
message
string
Valid values[
"The API key is forbidden to perform this request"
]
Payouts_v3_Http403RequestForbiddenError_Account
object (Payouts_v3_Http403RequestForbiddenError_Account)
error_code
string
Valid values[
"REQUEST_FORBIDDEN_ERROR"
]
message
string
Valid values[
"Your account is forbidden to perform this request"
]
Payouts_v3_Http403InvalidMerchantSettings_Payout
object (Payouts_v3_Http403InvalidMerchantSettings_Payout)
error_code
string
Valid values[
"INVALID_MERCHANT_SETTINGS"
]
message
string
Valid values[
"Payout failed because the source currency has not been activated. Please reach out to Xendit to activate this currency before retrying."
]
404
Not found
object
error_code
string
Valid values[
"DATA_NOT_FOUND"
]
message
string
Valid values[
"The Quote ID specified cannot be found"
]
409
Conflict
object
error_code
string
Valid values[
"DUPLICATE_ERROR"
]
message
string
Valid values[
"A payout with this idempotency key already exists. If you meant to execute a different request, please use another idempotency key."
]
500
Internal server error
object
error_code
string
Valid values[
"SERVER_ERROR"
]
message
string
Valid values[
"An unexpected error occurred"
]