Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
ModeWhen to use
With method_id + method_typeQuote a specific payment method — returns exact fees for that rail
Without method_idGeneric FX rate for display only
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
​
from_currency
string
required
Source currency (ISO 4217), e.g. "USD", "EUR".
​
to_currency
string
required
Target currency (ISO 4217), e.g. "USD", "CLP", "BRL", "MXN".
​
amount
number
required
Amount in the source currency.
​
method_id
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.
​
method_type
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
  }'

{
  "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:
ComponentDescription
floatPercentage-based fee — scales with amount
fixedFlat fee — charged regardless of amount
totalSum 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.