Examples

This page contains practical examples of using the Retorna SDK for Java.

Basic Example: Query Balance

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.account.BalanceResponse;

public class BasicExample {
    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 {
            BalanceResponse balance = client.account.getBalance();
            System.out.println("Balance: " + balance.getTotalBalance());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Complete Example: Payment Flow

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;
import com.retorna.sdk.order.CreateOrderInput;
import com.retorna.sdk.order.OrderResponse;
import com.retorna.sdk.order.PaymentInstructions;
import com.retorna.sdk.order.PaymentPurpose;

public class CompletePaymentFlow {
    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 {
            // 1. Create quotation
            CreateQuoteInput quoteInput = new CreateQuoteInput(
                "USD", "CO", "COP", 100.0, "BANK_TRANSFER", AmountType.SOURCE
            );
            QuoteResponse quote = client.quotation.createQuote(quoteInput);
            System.out.println("Quotation: " + quote.getId());
            System.out.println("Target amount: " + quote.getTargetAmount() + " COP");
            
            // 2. Create order
            PaymentInstructions instructions = new PaymentInstructions(
                "Banco de Bogotá",
                "1234567890",
                "CHECKING",
                "+573001234567",
                "001"
            );
            
            CreateOrderInput orderInput = new CreateOrderInput(
                quote.getId().intValue(),
                "ORD-" + System.currentTimeMillis(),
                "BANK_TRANSFER",
                "Juan", "Pérez", "juan@example.com", "+573001234567",
                "1234567890", "CC", "US", "US",
                "María", "García", "maria@example.com", "+573009876543",
                "9876543210", "CC",
                instructions,
                PaymentPurpose.FAMILY_SUPPORT
            );
            
            OrderResponse order = client.order.createPayoutOrder(orderInput);
            System.out.println("Order created: " + order.getId());
            System.out.println("Status: " + order.getStatus());
            
            // 3. Query order
            OrderResponse status = client.order.getOrderById(order.getId().toString());
            System.out.println("Current status: " + status.getStatus());
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Example: List Routes by Country

import com.retorna.sdk.account.PayoutRoute;
import java.util.List;
import java.util.Map;
import java.util.HashMap;

public class ListRoutesExample {
    public static void listRoutesByCountry(RetornaClient client, String country) {
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("country", country);
            
            List<PayoutRoute> routes = client.account.getRoutes(params);
            
            System.out.println("Available routes for " + country + ":");
            for (PayoutRoute route : routes) {
                System.out.println("- " + route.getName() + 
                    " (" + route.getStatus() + ")");
            }
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Example: Monitor Order Status

import java.util.concurrent.TimeUnit;

public class MonitorOrderExample {
    public static void monitorOrder(RetornaClient client, String orderId) {
        try {
            int maxAttempts = 10;
            int attempt = 0;
            
            while (attempt < maxAttempts) {
                OrderResponse order = client.order.getOrderById(orderId);
                String status = order.getStatus();
                
                System.out.println("Attempt " + (attempt + 1) + ": Status = " + status);
                
                if ("COMPLETED".equals(status)) {
                    System.out.println("✅ Order completed successfully");
                    break;
                } else if ("FAILED".equals(status) || "CANCELLED".equals(status)) {
                    System.out.println("❌ Order " + status.toLowerCase());
                    break;
                }
                
                attempt++;
                if (attempt < maxAttempts) {
                    TimeUnit.SECONDS.sleep(5); // Wait 5 seconds
                }
            }
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Example: Robust Error Handling

import com.retorna.sdk.errors.RetornaErrorReport;
import com.retorna.sdk.errors.RetornaErrorCategory;

public class ErrorHandlingExample {
    public static void safeOperation(RetornaClient client) {
        try {
            BalanceResponse balance = client.account.getBalance();
            System.out.println("Balance: " + balance.getTotalBalance());
        } catch (RuntimeException e) {
            // API error
            System.err.println("API error: " + e.getMessage());
            
            // You could parse the error here if the SDK provides it
            // RetornaErrorReport errorReport = parseError(e);
            // if (errorReport.getCategory() == RetornaErrorCategory.AUTHENTICATION) {
            //     // Handle authentication error
            // }
        } catch (IllegalArgumentException e) {
            // Validation error
            System.err.println("Validation error: " + e.getMessage());
        } catch (Exception e) {
            // General error
            System.err.println("Unexpected error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Example: Spring Boot Service

import org.springframework.stereotype.Service;
import org.springframework.beans.factory.annotation.Autowired;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.account.BalanceResponse;

@Service
public class RetornaService {
    
    @Autowired
    private RetornaClient retornaClient;
    
    public BalanceResponse getBalance() {
        try {
            return retornaClient.account.getBalance();
        } catch (Exception e) {
            throw new RuntimeException("Error fetching balance", e);
        }
    }
    
    public OrderResponse createOrder(CreateOrderInput input) {
        try {
            return retornaClient.order.createPayoutOrder(input);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Invalid order data", e);
        } catch (Exception e) {
            throw new RuntimeException("Error creating order", e);
        }
    }
}

Example: Multiple Quotations

public class MultipleQuotesExample {
    public static void compareQuotes(RetornaClient client) {
        try {
            // Quotation 1: 100 USD to COP
            CreateQuoteInput quote1Input = new CreateQuoteInput(
                "USD", "CO", "COP", 100.0, "BANK_TRANSFER", AmountType.SOURCE
            );
            QuoteResponse quote1 = client.quotation.createQuote(quote1Input);
            
            // Quotation 2: 200 USD to COP
            CreateQuoteInput quote2Input = new CreateQuoteInput(
                "USD", "CO", "COP", 200.0, "BANK_TRANSFER", AmountType.SOURCE
            );
            QuoteResponse quote2 = client.quotation.createQuote(quote2Input);
            
            System.out.println("Quotation 1 (100 USD): " + quote1.getTargetAmount() + " COP");
            System.out.println("Quotation 2 (200 USD): " + quote2.getTargetAmount() + " COP");
            System.out.println("Rate 1: " + quote1.getExchangeRate());
            System.out.println("Rate 2: " + quote2.getExchangeRate());
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Next Steps

• Error Handling - Learn to handle errors correctly
• Advanced Topics - Advanced SDK features