Quotation Guide

This guide shows you how to create and query quotations using the Retorna SDK.

Create a Quotation

Create a new quotation to get the exchange rate and amounts:

import com.retorna.sdk.quotation.CreateQuoteInput;
import com.retorna.sdk.quotation.QuoteResponse;
import com.retorna.sdk.quotation.AmountType;

CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD",              // sourceCurrency: Source currency
    "CO",               // targetCountry: Target country
    "COP",              // targetCurrency: Target currency
    100.0,              // amount: Amount
    "BANK_TRANSFER",    // payoutType: Payment type
    AmountType.SOURCE   // amountType: Amount type (SOURCE or TARGET)
);

QuoteResponse quote = client.quotation.createQuote(quoteInput);

System.out.println("Quotation ID: " + quote.getId());
System.out.println("Source amount: " + quote.getSourceAmount());
System.out.println("Target amount: " + quote.getTargetAmount());
System.out.println("Exchange rate: " + quote.getExchangeRate());

Quotation Parameters

CreateQuoteInput

Parameter	Type	Description	Required
sourceCurrency	String	Source currency code (e.g. "USD")	✅
targetCountry	String	Target country code (e.g. "CO")	✅
targetCurrency	String	Target currency code (e.g. "COP")	✅
amount	Double	Amount to quote	✅
payoutType	String	Payout platform type	✅
amountType	AmountType	SOURCE or TARGET	✅

AmountType

• SOURCE: The specified amount is in the source currency
• TARGET: The specified amount is in the target currency

Example with TARGET:

CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD",              // sourceCurrency
    "CO",               // targetCountry
    "COP",              // targetCurrency
    500000.0,           // amount in COP (target currency)
    "BANK_TRANSFER",    // payoutType
    AmountType.TARGET   // amountType: amount is in target
);

QuoteResponse quote = client.quotation.createQuote(quoteInput);
// quote.getSourceAmount() will show the equivalent in USD
// quote.getTargetAmount() will be 500000.0 COP

Query a Quotation

Get the details of an existing quotation by its ID:

String quoteId = "12345";
QuoteResponse quote = client.quotation.getQuoteById(quoteId);

System.out.println("ID: " + quote.getId());
System.out.println("Status: " + quote.getStatus());
System.out.println("Source amount: " + quote.getSourceAmount() + " " + quote.getSourceCurrency());
System.out.println("Target amount: " + quote.getTargetAmount() + " " + quote.getTargetCurrency());
System.out.println("Rate: " + quote.getExchangeRate());
System.out.println("Valid until: " + quote.getExpiresAt());

With Optional Parameters

import java.util.HashMap;
import java.util.Map;

Map<String, Object> params = new HashMap<>();
params.put("includeDetails", true);

QuoteResponse quote = client.quotation.getQuoteById(quoteId, params);

Available Payout Platforms

Different countries support different platforms:

Country	Available Platforms
Argentina	BANK_TRANSFER_AR
Colombia	CASH_PICKUP_CO, INTERBANK_TRANSFER_CO
Spain/EU	BANK_TRANSFER_EU
Peru	BANK_TRANSFER_USD_PE, BANK_TRANSFER_PEN_PE, CASH_PICKUP_PEN_PE, WALLET_PEN_PE
USA	BANK_TRANSFER_USD
Venezuela	BANK_TRANSFER, P2P_PHONE_TRANSFER, CASH_PICKUP_USD_VE

Complete Example

import com.retorna.sdk.config.Environment;
import com.retorna.sdk.config.LoggingLevel;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.core.RetornaClientOptions;
import com.retorna.sdk.quotation.CreateQuoteInput;
import com.retorna.sdk.quotation.QuoteResponse;
import com.retorna.sdk.quotation.AmountType;

public class QuotationExample {
    public static void main(String[] args) {
        RetornaClient client = RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.DEVELOP)
                .loggingLevel(LoggingLevel.INFO)
                .clientId(System.getenv("RETORNA_CLIENT_ID"))
                .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
                .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
                .build()
        );
        
        try {
            // Create quotation: 100 USD to COP
            CreateQuoteInput quoteInput = new CreateQuoteInput(
                "USD",
                "CO",
                "COP",
                100.0,
                "BANK_TRANSFER",
                AmountType.SOURCE
            );
            
            QuoteResponse quote = client.quotation.createQuote(quoteInput);
            
            System.out.println("=== Quotation Created ===");
            System.out.println("ID: " + quote.getId());
            System.out.println("Source: " + quote.getSourceAmount() + " " + quote.getSourceCurrency());
            System.out.println("Target: " + quote.getTargetAmount() + " " + quote.getTargetCurrency());
            System.out.println("Rate: " + quote.getExchangeRate());
            System.out.println("Valid until: " + quote.getExpiresAt());
            
            // Query quotation
            QuoteResponse retrievedQuote = client.quotation.getQuoteById(quote.getId().toString());
            System.out.println("\n=== Quotation Retrieved ===");
            System.out.println("Status: " + retrievedQuote.getStatus());
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Quotation Validation

Quotations have a validity period. Always verify:

QuoteResponse quote = client.quotation.getQuoteById(quoteId);

if (quote.getExpiresAt() != null) {
    LocalDateTime expiresAt = LocalDateTime.parse(quote.getExpiresAt());
    if (LocalDateTime.now().isAfter(expiresAt)) {
        System.out.println("⚠️ Quotation has expired. Create a new one.");
    }
}

Error Handling

try {
    QuoteResponse quote = client.quotation.createQuote(quoteInput);
} catch (IllegalArgumentException e) {
    // Invalid parameters
    System.err.println("Validation error: " + e.getMessage());
} catch (RuntimeException e) {
    // API error
    System.err.println("API error: " + e.getMessage());
} catch (Exception e) {
    // General error
    System.err.println("Error: " + e.getMessage());
    e.printStackTrace();
}

Recommended Flow

1. Create quotation before creating an order
2. Verify validity of the quotation
3. Use quotation ID when creating the order
4. Query quotation if you need to verify details

Next Step

• Orders Guide - Learn to create payment orders using quotations