Exchange Rates & Quotes

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' \
  -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' \
  -d '{
    "from_currency": "USD",
    "to_currency": "MXN",
    "amount": 200
  }'

const res = 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' },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'USD',
    method_id: 21,
    method_type: 'payout',
    amount: 406,
  }),
});
const { data } = await res.json();
// Show data.payout_data to customer, then use data.quote_id 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",
    "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 },
      "amount_due": 417.15,
      "exchange_rate": 1,
      "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"
      }
    }
  }
}

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' \
  -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' \
  -d '{
    "from_currency": "USD",
    "to_currency": "MXN",
    "amount": 200
  }'

const res = 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' },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'USD',
    method_id: 21,
    method_type: 'payout',
    amount: 406,
  }),
});
const { data } = await res.json();
// Show data.payout_data to customer, then use data.quote_id 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",
    "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 },
      "amount_due": 417.15,
      "exchange_rate": 1,
      "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"
      }
    }
  }
}

Yativo has two rate endpoints:

Endpoint	Use it to
`GET /exchange-rates`	Show live market rates for every wallet currency. No fees, no quote.
`POST /exchange-rate`	Price a specific payout or deposit with fees, and lock it with a `quote_id`.

POST /exchange-rate is the single source for pricing any transaction on Yativo. It returns a quote_id valid for 5 minutes — use this ID in the execution step to guarantee the rate and fee shown to your customer. There are two modes:

Mode	When to use
With `method_id` + `method_type`	Quote a specific payment method — returns exact fees for that rail
Without `method_id`	Generic FX rate for display only

Type Definitions

interface ExchangeRateRequest {
  from_currency: string;    // source currency (ISO 4217)
  to_currency: string;      // target currency (ISO 4217)
  amount: number;           // amount in source currency
  method_id?: number;       // payment method ID (from /payment-methods/payout or /payin)
  method_type?: "payout" | "payin";  // required when method_id is provided
  amount_type?: "send" | "receive";  // payout quotes only; default "send"
}

interface Quote {
  quote_id: string;         // valid for 5 minutes — use in /wallet/payout or /wallet/deposits/new
  quote_expire_at: string;  // ISO 8601
  from_currency: string;
  to_currency: string;
  rate: string;
  amount: string;           // send amount, in from_currency
  amount_type?: "send" | "receive";
  receive_amount?: string;  // receive mode only, in to_currency
  payout_data: {
    total_transaction_fee_in_from_currency: string;
    total_transaction_fee_in_to_currency: string;
    customer_sent_amount: string;
    customer_receive_amount: string;
    customer_total_amount_due: string;  // total deducted from wallet
  };
  calculator: {
    amount_due: number;
    exchange_rate: number;
    fee_breakdown: {
      float: { wallet_currency: number; payout_currency: number };
      fixed: { wallet_currency: number; payout_currency: number };
      total: number;
    };
    PayoutMethod?: {        // present when method_id was provided
      id: number;
      method_name: string;
      country: string;
      currency: string;
      base_currency: string;
    };
  };
}

Generate a Quote

POST /exchange-rate

string

required

Source currency (ISO 4217), e.g. "USD", "EUR".

string

required

Target currency (ISO 4217), e.g. "USD", "CLP", "BRL", "MXN".

number

required

Amount in the source currency.

integer

Payment method ID from GET /payment-methods/payout or GET /payment-methods/payin. Scopes the quote to the exact fees for that rail — required for checkout flows where you will execute at the quoted price.

string

"payout" for sends/withdrawals or "payin" for deposits. Required when method_id is provided.

string

default:"send"

Payout quotes only. Set to "receive" to make amount the amount the customer receives, in to_currency. See Pay out by receive amount.

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' \
  -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' \
  -d '{
    "from_currency": "USD",
    "to_currency": "MXN",
    "amount": 200
  }'

const res = 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' },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'USD',
    method_id: 21,
    method_type: 'payout',
    amount: 406,
  }),
});
const { data } = await res.json();
// Show data.payout_data to customer, then use data.quote_id 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",
    "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 },
      "amount_due": 417.15,
      "exchange_rate": 1,
      "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"
      }
    }
  }
}

Quotes expire after 5 minutes. Execute the transaction within this window — after expiry the quote_id is rejected and a new quote is required.

Execute the Quote

Use the quote_id in the appropriate execution endpoint:

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"
  }'

For deposits (payin)

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"
  }'

Pay out by receive amount

By default, a payout’s amount is what you send from your wallet, and the customer receives that amount converted into the payout currency. To fix what the customer receives instead, for example exactly 5,000 MXN, set amount_type to receive. Yativo works out the send amount and fees, then debits your wallet for both. The customer always gets the full requested amount.

`amount_type`	`amount` means	Currency of `amount`
`send` (default)	What leaves your wallet, before fees	Your debit wallet (`from_currency` / `debit_wallet`)
`receive`	What the customer receives	The payout currency (`to_currency`)

amount_type works on POST /exchange-rate (payout quotes) and POST /wallet/payout.

Option A: quote first (recommended)

A quote fixes the rate and fees for 5 minutes, so you can show the exact debit before you commit.

Get a receive-mode quote

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-receive-001' \
  -d '{
    "method_type": "payout",
    "method_id": 12,
    "from_currency": "USD",
    "to_currency": "MXN",
    "amount": 5000,
    "amount_type": "receive"
  }'

{
  "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",
    "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" }
  }
}

amount is the send amount in from_currency, receive_amount is what the customer gets, and payout_data.customer_total_amount_due is the total your wallet is debited.

Create the payout with the quote

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-receive-001' \
  -d '{
    "quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
    "payment_method_id": 555,
    "debit_wallet": "USD",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
  }'

The quote supplies the amount, so don’t send amount or amount_type. Any amount_type you send with a quote_id is ignored. The quote’s method_id must be the payout method behind payment_method_id.

Option B: pay out directly

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-receive-002' \
  -d '{
    "amount": 5000,
    "amount_type": "receive",
    "payment_method_id": 555,
    "debit_wallet": "USD",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
  }'

The send amount is calculated at the current rate when the request is processed. Use Option A if you need to know the debit in advance.

Payout response

Every POST /wallet/payout response includes these fields, in either mode:

Field	Meaning
`amount_type`	`send` or `receive`, as applied.
`send_amount`	The amount sent, in the debit wallet currency, before fees.
`customer_receive_amount`	The amount the customer receives, in `currency`.
`debit_amount`	The total debited from your wallet, fees included.

When the debit wallet and payout currency are the same (for example USD to USD), the send amount equals the receive amount. Fees are still added on top.

Limits and errors

The payout method’s minimum and maximum are checked against the calculated send amount, so a receive amount can be rejected for being above or below a limit. The error shows the limit in your wallet currency.
If your wallet can’t cover the send amount plus fees, the request fails with Insufficient wallet balance and nothing is debited.
An amount_type other than send or receive returns 422.
amount_type: "receive" on a payin quote returns 422.

Live market rates

To show live rates to your customers, without fees or a quote, use:

GET /exchange-rates?base=USD

string

default:"USD"

The currency rates are quoted against. Must be a supported wallet currency.

curl 'https://api.yativo.com/api/v1/exchange-rates?base=USD' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "base": "USD",
    "rates": {
      "ARS": 1185.5,
      "BRL": 5.4321,
      "EUR": 0.9187,
      "MXN": 18.6024,
      "USD": 1
    },
    "updated_at": "2026-10-01T12:00:00+00:00"
  }
}

Each rate means 1 base = rate units of that currency. To convert from the base currency, multiply by the rate. To convert back, divide. A rate of null means no rate is available for that currency right now.

Rates are indicative market rates. They refresh about once a minute and don’t include fees.
You can call this endpoint once per minute per account. Further calls in the same minute get 429 with a Retry-After header. To show several bases, make one request and divide: the rate from A to B is rates[B] / rates[A].
Team members need the Currency Exchange → view permission.
An unsupported base returns 422 with the allowed values. 503 means rates are temporarily unavailable.

See Get Market Rates for the full reference.

Get a Locked Quote for Send Money

For sending money specifically (rather than wallet payouts), use the dedicated send money quote endpoint which also returns a quote_id:

POST /sendmoney/quote

curl -X POST 'https://api.yativo.com/api/v1/sendmoney/quote' \
  -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": "MXN",
    "amount": 200,
    "beneficiary_payment_method_id": "pm-3a4b5c6d-7e8f-9a0b"
  }'

Complete Quote Workflow

1. GET /payment-methods/payout?country=...    → get method_id (e.g. 21)
2. POST /exchange-rate                         → quote with method_id + method_type
                                               → shows exact fees to customer
                                               → returns quote_id (5-min window)
3. POST /wallet/payout (or /deposits/new)      → execute with quote_id
4. GET /transaction/tracking/{id}              → monitor status

Fee Breakdown

The calculator.fee_breakdown object contains two fee components:

Component	Description
`float`	Percentage-based fee — scales with amount
`fixed`	Flat fee — charged regardless of amount
`total`	Sum of float + fixed in both wallet and payout currencies

Always display payout_data.customer_total_amount_due to the customer — this is the exact amount that will be debited from their wallet.

Rate Limits

POST /exchange-rate is limited to 30 requests per minute per API key. Cache quotes client-side for display rather than calling on every user keystroke. GET /exchange-rates is limited to 1 request per minute per account. Its rates only refresh once a minute.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

Exchange Rates & Quotes

Generate a Quote

Execute the Quote

For payouts

For deposits (payin)

Pay out by receive amount

Option A: quote first (recommended)

Option B: pay out directly

Payout response

Limits and errors

Live market rates

Get a Locked Quote for Send Money

Complete Quote Workflow

Fee Breakdown

Rate Limits

​Generate a Quote

​Execute the Quote

​For payouts

​For deposits (payin)

​Pay out by receive amount

​Option A: quote first (recommended)

​Option B: pay out directly

​Payout response

​Limits and errors

​Live market rates

​Get a Locked Quote for Send Money

​Complete Quote Workflow

​Fee Breakdown

​Rate Limits

Generate a Quote

Execute the Quote

For payouts

For deposits (payin)

Pay out by receive amount

Option A: quote first (recommended)

Option B: pay out directly

Payout response

Limits and errors

Live market rates

Get a Locked Quote for Send Money

Complete Quote Workflow

Fee Breakdown

Rate Limits