Spanish

Exchange Rate

Overview

The Yativo Exchange Rate API allows you to retrieve real-time exchange rates and calculate transaction fees for currency conversions with various payout methods. This endpoint generates quotes that are valid for 5 minutes and can be used to execute transactions through the deposit and payout endpoints.

Base URL

https://api.yativo.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header.

Get Exchange Rate

Endpoint

POST /exchange-rate

Headers

Header
Type
Required
Description

Content-Type

string

Yes

Must be application/json

Authorization

string

Yes

Bearer token for authentication

Request Body Parameters

Parameter
Type
Required
Description

from_currency

string

Yes

Source currency code (ISO 4217)

to_currency

string

Yes

Target currency code (ISO 4217)

method_id

integer

Yes

Payout method identifier

method_type

string

Yes

Transaction type: "payin" or "payout"

amount

number

Yes

Amount to convert in the source currency

Example Request

curl --location 'https://api.yativo.com/api/v1/exchange-rate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciO...' \
--data '{
    "from_currency": "USD",
    "to_currency": "USD",
    "method_id": 21,
    "method_type": "payout",
    "amount": 406
}'

Response Structure

Success Response (200 OK)

response.json
{
    "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": "PayPal",
                "country": "PER",
                "currency": "USD",
                "payment_method_code": null,
                "cutoff_hrs_start": null,
                "cutoff_hrs_end": null,
                "base_currency": "USD",
                "exchange_rate_float": "0",
                "expiration_time": null
            }
        }
    }
}

Response Fields Explanation

Root level:

  • status: Status of the API call ("success" or "error")

  • status_code: HTTP status code

  • message: Human-readable message about the request

  • data: Main response data object

Data object:

  • quote_id: Unique identifier for the quote (valid for 5 minutes)

  • from_currency: Source currency code

  • to_currency: Target currency code

  • rate: Base exchange rate (as string with 8 decimal places)

  • amount: Original amount being converted

  • converted_amount: Formatted conversion description

Payout data:

  • total_transaction_fee_in_from_currency: Total fees in source currency

  • total_transaction_fee_in_to_currency: Total fees in target currency

  • customer_sent_amount: Amount customer sends

  • customer_receive_amount: Amount customer receives after fees

  • customer_total_amount_due: Total amount customer needs to pay

Calculator object (detailed breakdown):

  • Fee information:

    • total_fee: Total fees in wallet currency, payout currency, and USD

    • fee_breakdown: Breakdown of fees into float and fixed components

  • Amount information:

    • total_amount: Total transaction amount in both currencies

    • amount_due: Total amount the customer owes

    • debit_amount: Amount to be debited from customer's account

    • customer_receive_amount: Final amount recipient receives

  • Rate information:

    • exchange_rate: Base exchange rate

    • adjusted_rate: Exchange rate after adjustments

    • target_currency: Target currency for the transaction

    • base_currencies: Array of supported base currencies

Payout method:

  • id: Method identifier

  • method_name: Display name (e.g., "PayPal")

  • country: Country code where method is available

  • currency: Currency supported by this method

  • base_currency: Base currency for this method

  • exchange_rate_float: Additional rate adjustment

  • cutoff_hrs_start/end: Processing time windows (if applicable)

  • expiration_time: Rate validity period (if applicable)

Using the Quote ID

The quote_id returned in the response can be used to execute transactions within 5 minutes of generation.

1

Deposits (Payin)

Example request to create a deposit using a quote:

POST /wallet/deposits/new
{
    "gateway": 20,
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "currency": "USD",
    "redirect_url": "https://google.com"  // optional
}
2

Payouts

Example request to execute a payout using a quote:

POST /wallet/payout
{
    "debit_wallet": "USD",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "amount": 406,
    "payment_method_id": 21
}

Error Handling

The API returns standard HTTP status codes. Common error responses include:

400 Bad Request

{
    "status": "error",
    "status_code": 400,
    "message": "Invalid request parameters",
    "errors": ["Invalid currency code"]
}

401 Unauthorized

{
    "status": "error",
    "status_code": 401,
    "message": "Authentication failed"
}

404 Not Found

{
    "status": "error",
    "status_code": 404,
    "message": "Payout method not found"
}

Usage Examples

Cross-Currency Exchange

curl --location 'https://api.yativo.com/api/v1/exchange-rate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
    "from_currency": "USD",
    "to_currency": "EUR",
    "method_id": 15,
    "method_type": "payout",
    "amount": 1000
}'

Payin Transaction Quote

curl --location 'https://api.yativo.com/api/v1/exchange-rate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
    "from_currency": "GBP",
    "to_currency": "USD",
    "method_id": 8,
    "method_type": "payin",
    "amount": 500
}'

Important Notes

  • Quote Validity: Quotes are valid for 5 minutes from generation

  • Rate Lock: Exchange rates are locked during the quote validity period

  • Two-Step Process: Generate quote first, then execute transaction using the quote_id

  • Method Consistency: Use the same method_id in both quote generation and transaction execution

  • Amount Matching: Ensure the amount in the execution request matches the quote amount

Rate Limits

  • Maximum 100 requests per minute per API key

  • Rate limit headers are included in all responses

Support

For API support and questions, contact: [email protected]

Last Updated: September 2025 API Version: v1

PreviousDocument VerificationNextPayins