curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "USD",
"method_id": 21,
"method_type": "payout",
"amount": 406
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "CLP",
"amount": 500
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-002' \
-d '{
"from_currency": "USD",
"to_currency": "MXN",
"method_id": 12,
"method_type": "payout",
"amount": 5000,
"amount_type": "receive"
}'
const response = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: {
'X-Api-Key': process.env.YATIVO_API_KEY,
'X-Api-Secret': process.env.YATIVO_API_SECRET,
'Content-Type': 'application/json',
'Idempotency-Key': `quote-${Date.now()}`,
},
body: JSON.stringify({
from_currency: 'USD',
to_currency: 'USD',
method_id: 21,
method_type: 'payout',
amount: 406,
}),
});
const { data } = await response.json();
// data.quote_id is valid for 5 minutes — use it in /wallet/payout
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"from_currency": "USD",
"to_currency": "USD",
"rate": "1.00000000",
"amount": "406.00000000",
"converted_amount": "1USD - 1.00000000 USD",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "11.15",
"customer_sent_amount": "406.00",
"customer_receive_amount": "406.00",
"customer_total_amount_due": "417.15"
},
"calculator": {
"total_fee": {
"wallet_currency": 11.15,
"payout_currency": 11.15,
"usd": 11.15
},
"total_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"amount_due": 417.15,
"exchange_rate": 1,
"adjusted_rate": 1,
"target_currency": "USD",
"base_currencies": ["USD"],
"debit_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"customer_receive_amount": {
"wallet_currency": 406,
"payout_currency": 406
},
"fee_breakdown": {
"float": {
"wallet_currency": 10.15,
"payout_currency": 10.15
},
"fixed": {
"wallet_currency": 1,
"payout_currency": 1
},
"total": 11.15
},
"PayoutMethod": {
"id": 21,
"method_name": "Bank Transfer",
"country": "PER",
"currency": "USD",
"base_currency": "USD",
"exchange_rate_float": "0"
}
}
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
"quote_expire_at": "2026-10-01T12:05:00.000000Z",
"from_currency": "USD",
"to_currency": "MXN",
"rate": "18.12340000",
"amount": "275.88642300",
"amount_type": "receive",
"receive_amount": "5000.00000000",
"converted_amount": "1USD - 18.12340000 MXN",
"payout_data": {
"customer_sent_amount": "275.89",
"customer_receive_amount": "5,000.00",
"customer_total_amount_due": "278.39"
},
"calculator": { "...": "full fee and rate breakdown" }
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "7b91acf8-9d2a-4e38-aa71-9babe9f785cd",
"from_currency": "USD",
"to_currency": "CLP",
"rate": "950.00000000",
"amount": "500.00000000",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "10592.50",
"customer_sent_amount": "500.00",
"customer_receive_amount": "462925.00",
"customer_total_amount_due": "511.15"
},
"calculator": {
"fee_breakdown": {
"float": { "wallet_currency": 10.15, "payout_currency": 9642.50 },
"fixed": { "wallet_currency": 1, "payout_currency": 950 },
"total": 11.15
},
"exchange_rate": 950,
"customer_receive_amount": { "wallet_currency": 500, "payout_currency": 475000 }
}
}
}
Payments & Transfers
Get Exchange Rate / Quote
Generate a quote with locked rate and fee breakdown for a payout or deposit
POST
/
exchange-rate
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "USD",
"method_id": 21,
"method_type": "payout",
"amount": 406
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "CLP",
"amount": 500
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-002' \
-d '{
"from_currency": "USD",
"to_currency": "MXN",
"method_id": 12,
"method_type": "payout",
"amount": 5000,
"amount_type": "receive"
}'
const response = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: {
'X-Api-Key': process.env.YATIVO_API_KEY,
'X-Api-Secret': process.env.YATIVO_API_SECRET,
'Content-Type': 'application/json',
'Idempotency-Key': `quote-${Date.now()}`,
},
body: JSON.stringify({
from_currency: 'USD',
to_currency: 'USD',
method_id: 21,
method_type: 'payout',
amount: 406,
}),
});
const { data } = await response.json();
// data.quote_id is valid for 5 minutes — use it in /wallet/payout
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"from_currency": "USD",
"to_currency": "USD",
"rate": "1.00000000",
"amount": "406.00000000",
"converted_amount": "1USD - 1.00000000 USD",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "11.15",
"customer_sent_amount": "406.00",
"customer_receive_amount": "406.00",
"customer_total_amount_due": "417.15"
},
"calculator": {
"total_fee": {
"wallet_currency": 11.15,
"payout_currency": 11.15,
"usd": 11.15
},
"total_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"amount_due": 417.15,
"exchange_rate": 1,
"adjusted_rate": 1,
"target_currency": "USD",
"base_currencies": ["USD"],
"debit_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"customer_receive_amount": {
"wallet_currency": 406,
"payout_currency": 406
},
"fee_breakdown": {
"float": {
"wallet_currency": 10.15,
"payout_currency": 10.15
},
"fixed": {
"wallet_currency": 1,
"payout_currency": 1
},
"total": 11.15
},
"PayoutMethod": {
"id": 21,
"method_name": "Bank Transfer",
"country": "PER",
"currency": "USD",
"base_currency": "USD",
"exchange_rate_float": "0"
}
}
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
"quote_expire_at": "2026-10-01T12:05:00.000000Z",
"from_currency": "USD",
"to_currency": "MXN",
"rate": "18.12340000",
"amount": "275.88642300",
"amount_type": "receive",
"receive_amount": "5000.00000000",
"converted_amount": "1USD - 18.12340000 MXN",
"payout_data": {
"customer_sent_amount": "275.89",
"customer_receive_amount": "5,000.00",
"customer_total_amount_due": "278.39"
},
"calculator": { "...": "full fee and rate breakdown" }
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "7b91acf8-9d2a-4e38-aa71-9babe9f785cd",
"from_currency": "USD",
"to_currency": "CLP",
"rate": "950.00000000",
"amount": "500.00000000",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "10592.50",
"customer_sent_amount": "500.00",
"customer_receive_amount": "462925.00",
"customer_total_amount_due": "511.15"
},
"calculator": {
"fee_breakdown": {
"float": { "wallet_currency": 10.15, "payout_currency": 9642.50 },
"fixed": { "wallet_currency": 1, "payout_currency": 950 },
"total": 11.15
},
"exchange_rate": 950,
"customer_receive_amount": { "wallet_currency": 500, "payout_currency": 475000 }
}
}
}
Returns a real-time exchange rate, fee breakdown, and a
For deposits (payin):
quote_id valid for 5 minutes. Pass the quote_id to POST /wallet/payout or POST /wallet/deposits/new to execute the transaction at the quoted rate.
POST https://api.yativo.com/api/v1/exchange-rate
Requires an
Idempotency-Key header. Rate-limited to 30 requests per minute. This endpoint both prices the transaction AND generates a binding quote_id — treat it as quote creation, not just a rate lookup.curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "USD",
"method_id": 21,
"method_type": "payout",
"amount": 406
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "CLP",
"amount": 500
}'
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-002' \
-d '{
"from_currency": "USD",
"to_currency": "MXN",
"method_id": 12,
"method_type": "payout",
"amount": 5000,
"amount_type": "receive"
}'
const response = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: {
'X-Api-Key': process.env.YATIVO_API_KEY,
'X-Api-Secret': process.env.YATIVO_API_SECRET,
'Content-Type': 'application/json',
'Idempotency-Key': `quote-${Date.now()}`,
},
body: JSON.stringify({
from_currency: 'USD',
to_currency: 'USD',
method_id: 21,
method_type: 'payout',
amount: 406,
}),
});
const { data } = await response.json();
// data.quote_id is valid for 5 minutes — use it in /wallet/payout
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"from_currency": "USD",
"to_currency": "USD",
"rate": "1.00000000",
"amount": "406.00000000",
"converted_amount": "1USD - 1.00000000 USD",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "11.15",
"customer_sent_amount": "406.00",
"customer_receive_amount": "406.00",
"customer_total_amount_due": "417.15"
},
"calculator": {
"total_fee": {
"wallet_currency": 11.15,
"payout_currency": 11.15,
"usd": 11.15
},
"total_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"amount_due": 417.15,
"exchange_rate": 1,
"adjusted_rate": 1,
"target_currency": "USD",
"base_currencies": ["USD"],
"debit_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"customer_receive_amount": {
"wallet_currency": 406,
"payout_currency": 406
},
"fee_breakdown": {
"float": {
"wallet_currency": 10.15,
"payout_currency": 10.15
},
"fixed": {
"wallet_currency": 1,
"payout_currency": 1
},
"total": 11.15
},
"PayoutMethod": {
"id": 21,
"method_name": "Bank Transfer",
"country": "PER",
"currency": "USD",
"base_currency": "USD",
"exchange_rate_float": "0"
}
}
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
"quote_expire_at": "2026-10-01T12:05:00.000000Z",
"from_currency": "USD",
"to_currency": "MXN",
"rate": "18.12340000",
"amount": "275.88642300",
"amount_type": "receive",
"receive_amount": "5000.00000000",
"converted_amount": "1USD - 18.12340000 MXN",
"payout_data": {
"customer_sent_amount": "275.89",
"customer_receive_amount": "5,000.00",
"customer_total_amount_due": "278.39"
},
"calculator": { "...": "full fee and rate breakdown" }
}
}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "7b91acf8-9d2a-4e38-aa71-9babe9f785cd",
"from_currency": "USD",
"to_currency": "CLP",
"rate": "950.00000000",
"amount": "500.00000000",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "10592.50",
"customer_sent_amount": "500.00",
"customer_receive_amount": "462925.00",
"customer_total_amount_due": "511.15"
},
"calculator": {
"fee_breakdown": {
"float": { "wallet_currency": 10.15, "payout_currency": 9642.50 },
"fixed": { "wallet_currency": 1, "payout_currency": 950 },
"total": 11.15
},
"exchange_rate": 950,
"customer_receive_amount": { "wallet_currency": 500, "payout_currency": 475000 }
}
}
}
Response fields
| Field | Description |
|---|---|
quote_id | Binding quote identifier — valid for 5 minutes |
quote_expire_at | When the quote expires. Use it before this time. |
rate | Exchange rate applied (source → target currency) |
amount | The send amount, in from_currency. In receive mode this is calculated for you. |
amount_type | Payout quotes: send or receive. |
receive_amount | Only in receive mode: the amount the customer receives, in to_currency. |
payout_data.customer_total_amount_due | Total deducted from your wallet (amount + fees) |
payout_data.customer_receive_amount | In receive mode, the amount the customer receives. In send mode, read calculator.customer_receive_amount.payout_currency for the amount the customer receives. |
calculator.customer_receive_amount.payout_currency | The amount the customer receives, in to_currency |
payout_data.total_transaction_fee_in_from_currency | Total fees in the source currency |
calculator.fee_breakdown.float | Percentage-based fee component |
calculator.fee_breakdown.fixed | Flat fee component |
calculator.amount_due | Final wallet debit amount |
calculator.PayoutMethod | Payment method details (only when method_id provided) |
Using the quote_id
Once you have aquote_id, use it in the execution step within 5 minutes:
For payouts:
curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: payout-001' \
-d '{
"debit_wallet": "USD",
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"payment_method_id": 555,
"customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
}'
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-001' \
-d '{
"gateway": 20,
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"currency": "USD",
"redirect_url": "https://your-app.com/deposit/complete"
}'
Quotes expire after 5 minutes and cannot be reused. Generating a quote and letting it expire before executing wastes a rate lock and a request toward your rate limit.
Authorizations
Your API key (yativo_pk_...) from Developers → API Keys. Send together with X-Api-Secret.
Your API secret (yativo_sk_...), shown once when the key is created.
Headers
A unique string per request to ensure idempotent processing.
Body
application/json
Source currency code (ISO 4217), e.g. "USD", "EUR".
Example:
"USD"
Target currency code (ISO 4217), e.g. "USD", "CLP", "BRL", "MXN".
Example:
"CLP"
Amount in the source currency to convert. With amount_type: "receive", the amount the customer receives in to_currency.
Example:
500
The payment method ID (from GET /payment-methods/payout or GET /payment-methods/payin). When provided, the quote is scoped to that specific payment rail and its exact fee structure is applied.
Transaction direction: "payout" (for sends/withdrawals) or "payin" (for deposits). Required when method_id is provided.
Available options:
payout, payin Payout quotes only. send (default): amount is what leaves your wallet. receive: amount is what the customer receives, and the quote works out the send amount and fees. Using receive with method_type: "payin" returns 422. See Pay out by receive amount.
Available options:
send, receive