Quote ID API Documentation

Overview

The Quote ID system allows you to create and execute financial transactions (deposits and payouts) using pre-generated quotes. This ensures consistent exchange rates and fee calculations between quote generation and transaction execution. The process involves two steps: creating a quote and then executing the transaction.

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

Step 1: Creating a Quote

Endpoint

POST /exchange-rate

Request Parameters

{
    "from_currency": "USD",
    "to_currency": "USD",
    "method_id": 21,
    "method_type": "payout",
    "amount": 406
}

Parameters:

from_currency (string): Source currency code (e.g., "USD", "EUR", "GBP")
to_currency (string): Target currency code (e.g., "USD", "EUR", "GBP")
method_id (integer): Payment method identifier
method_type (string): Transaction type - either "payout" or "payin" (for deposits)
amount (number): Amount to convert in the source currency

Response Format

{
    "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:

quote_id: Unique identifier for this specific quote (valid for 5 minutes)
rate: Exchange rate applied to the transaction
amount: Original amount requested
converted_amount: Conversion description showing rate
payout_data: Transaction summary with fees and amounts
calculator: Detailed breakdown of all calculations and fees

Step 2: Executing the Transaction

Once you have a quote_id, you can execute the transaction using one of the following endpoints.

For Deposits (Payin)

Endpoint: POST /wallet/deposits/new

Request Parameters

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

Parameters:

gateway (integer): Gateway identifier for the payment processor
quote_id (string): Quote ID obtained from the exchange-rate endpoint
currency (string): Target currency code
redirect_url (string, optional): URL to redirect user after transaction completion

For Payouts

Endpoint: POST /wallet/payout

Request Parameters

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

Parameters:

debit_wallet (string): Currency code of the wallet to debit from
quote_id (string): Quote ID obtained from the exchange-rate endpoint
amount (number): Amount to send (should match the original quote amount)
payment_method_id (integer): Payment method ID (should match the method_id used in quote creation)

Quote Data Breakdown

Payout Data Section

total_transaction_fee_in_from_currency: Total fees in source currency
total_transaction_fee_in_to_currency: Total fees in destination currency
customer_sent_amount: Amount customer is sending
customer_receive_amount: Amount recipient will receive
customer_total_amount_due: Total amount including fees

Calculator Section

Total Fee: Fees broken down by currency (wallet, payout, USD)
Total Amount: Complete transaction amounts in different currencies
Amount Due: Final amount to be debited from wallet
Exchange Rates: Market rate and adjusted rate applied
Fee Breakdown: Itemized fees (float fees and fixed fees)
Payment Method: Details about the selected payment method

Best Practices

Quote Validity: Quotes are valid for 5 minutes from generation — execute transactions promptly.
Two-Step Process: Always create a quote first, then execute the transaction using the quote_id.
Amount Consistency: Ensure the amount in the execution request matches the quote amount.
Method ID Matching: Use the same method_id in both quote creation and transaction execution.
Error Handling: Always check the status and status_code fields before processing data.
Fee Transparency: Display all fees from the calculator breakdown to users.
Currency Validation: Verify currency codes match your intended transaction flow.

Quotes expire after 5 minutes and exchange rates are locked during the quote validity period.

Complete Workflow Example

Create a Payout Quote

Request:

POST https://api.yativo.com/api/v1/exchange-rate
{
    "from_currency": "USD",
    "to_currency": "USD",
    "method_id": 21,
    "method_type": "payout",
    "amount": 406
}

Execute the Payout

Request:

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

Error Handling

Standard success response

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful"
}

Common error causes

Expired quote_id (after 5 minutes)
Invalid payment method ID
Insufficient wallet balance
Currency mismatch errors

Non-successful responses will have different status and status_code values with error details in the message field.

Integration Notes

All requests should be made to the base URL: https://api.yativo.com/api/v1
Quotes expire after 5 minutes and cannot be reused
Exchange rates are locked during the quote validity period
Method types are "payout" for withdrawals and "payin" for deposits
Payment method IDs must correspond to valid, active payment methods
Always use the exact quote_id returned from the exchange-rate endpoint

PreviousWallet Balance NextSupported Additional Documents for KYB