Exchange Rates & Quotes

curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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: { 'Authorization': `Bearer ${token}`, '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": "PayPal",
        "country": "PER",
        "currency": "USD",
        "base_currency": "USD"
      }
    }
  }
}

The POST /exchange-rate endpoint 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
}

interface Quote {
  quote_id: string;         // valid for 5 minutes — use in /wallet/payout or /wallet/deposits/new
  from_currency: string;
  to_currency: string;
  rate: string;
  amount: string;
  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.

curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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: { 'Authorization': `Bearer ${token}`, '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": "PayPal",
        "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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-001' \
  -d '{
    "debit_wallet": "USD",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "amount": 406,
    "payment_method_id": 21
  }'

For deposits (payin)

curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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"
  }'

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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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

The exchange rate endpoint is limited to 30 requests per minute per API key. Cache quotes client-side for display rather than calling on every user keystroke.

Payouts Deposits (Payins)

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)

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)

​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)

Get a Locked Quote for Send Money

Complete Quote Workflow

Fee Breakdown

Rate Limits