Orders Guide

This guide shows you how to create and manage payment orders using the Retorna SDK.

Create a Payment Order

Create a new payment order. You first need a valid quotation:

import com.retorna.sdk.order.CreateOrderInput;
import com.retorna.sdk.order.OrderResponse;
import com.retorna.sdk.order.PaymentInstructions;
import com.retorna.sdk.order.PaymentPurpose;

// First, create a quotation
CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD", "CO", "COP", 100.0, "BANK_TRANSFER", AmountType.SOURCE
);
QuoteResponse quote = client.quotation.createQuote(quoteInput);

// Then, create the order using the quotation ID
PaymentInstructions instructions = new PaymentInstructions(
    "Example Bank",       // bankName
    "1234567890",        // accountNumber
    "CHECKING",          // accountType
    "+573001234567",     // phoneNumber
    "001"                // branchId (optional)
);

CreateOrderInput orderInput = new CreateOrderInput(
    quote.getId().intValue(),        // pogQuotationId: Quotation ID
    "ORD-2024-001",                  // externalId: Unique external ID
    "BANK_TRANSFER",                 // payoutTypePlatformName
    "Juan",                          // senderNames
    "Pérez",                         // senderLastNames
    "juan.perez@example.com",        // senderEmail
    "+573001234567",                 // senderPhone
    "1234567890",                    // senderDocumentId
    "CC",                            // senderDocumentType
    "US",                            // senderCountry
    "US",                            // sourceCountry
    "María",                         // beneficiaryNames
    "García",                        // beneficiaryLastNames
    "maria.garcia@example.com",      // beneficiaryEmail
    "+573009876543",                 // beneficiaryPhone
    "9876543210",                    // beneficiaryDocumentId
    "CC",                            // beneficiaryDocumentType
    instructions,                    // paymentInstructions
    PaymentPurpose.FAMILY_SUPPORT    // paymentPurpose
);

OrderResponse order = client.order.createPayoutOrder(orderInput);

System.out.println("Order created: " + order.getId());
System.out.println("Status: " + order.getStatus());
System.out.println("Amount: " + order.getAmount());

Order Parameters

CreateOrderInput

Quotation Information

• pogQuotationId (Integer): ID of the previously created quotation

External Identification

• externalId (String): Unique external ID for your reference

Payout Platform

• payoutTypePlatformName (String): Platform name (e.g. "BANK_TRANSFER")

Sender Information

• senderNames (String): Sender first name
• senderLastNames (String): Sender last name
• senderEmail (String): Sender email
• senderPhone (String): Sender phone
• senderDocumentId (String): Document number
• senderDocumentType (String): Document type (CC, CE, PASSPORT, etc.)
• senderCountry (String): Sender country code
• sourceCountry (String): Source country code

Beneficiary Information

• beneficiaryNames (String): Beneficiary first name
• beneficiaryLastNames (String): Beneficiary last name
• beneficiaryEmail (String): Beneficiary email
• beneficiaryPhone (String): Beneficiary phone
• beneficiaryDocumentId (String): Document number
• beneficiaryDocumentType (String): Document type

Payment Instructions

• paymentInstructions (PaymentInstructions): Payment-specific instructions
• paymentPurpose (PaymentPurpose): Payment purpose

PaymentInstructions

Depends on the platform, but generally includes:

PaymentInstructions instructions = new PaymentInstructions(
    "Example Bank",       // bankName: Bank name
    "1234567890",        // accountNumber: Account number
    "CHECKING",          // accountType: Account type (CHECKING, SAVINGS)
    "+573001234567",     // phoneNumber: Phone
    "001"                // branchId: Branch ID (optional)
);

PaymentPurpose

Available purposes:

• FAMILY_SUPPORT - Family support
• BUSINESS_PAYMENT - Business payment
• SALARY - Salary
• OTHER - Other

Query an Order

Get the details of an existing order:

String orderId = "12345";
OrderResponse order = client.order.getOrderById(orderId);

System.out.println("ID: " + order.getId());
System.out.println("Status: " + order.getStatus());
System.out.println("Amount: " + order.getAmount());
System.out.println("Currency: " + order.getCurrency());
System.out.println("Created at: " + order.getCreatedAt());

With Optional Parameters

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

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

OrderResponse order = client.order.getOrderById(orderId, params);

Automatic Validation

The SDK automatically validates data according to the selected payout platform. Each country has specific validators:

• Argentina: Validates CUIT, CBU format, etc.
• Colombia: Validates ID, bank account format, etc.
• Peru: Validates DNI, interbank account format, etc.
• Spain: Validates NIE/NIF, IBAN format, etc.
• USA: Validates SSN, bank account format, etc.
• Venezuela: Validates ID, bank account format, etc.

If validation fails, you will receive an exception before the request is sent to the API.

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;
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 OrderExample {
    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 {
            // Step 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 created: " + quote.getId());
            
            // Step 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.perez@example.com",
                "+573001234567",
                "1234567890",
                "CC",
                "US",
                "US",
                "María",
                "García",
                "maria.garcia@example.com",
                "+573009876543",
                "9876543210",
                "CC",
                instructions,
                PaymentPurpose.FAMILY_SUPPORT
            );
            
            OrderResponse order = client.order.createPayoutOrder(orderInput);
            
            System.out.println("\n=== Order Created ===");
            System.out.println("ID: " + order.getId());
            System.out.println("Status: " + order.getStatus());
            System.out.println("Amount: " + order.getAmount());
            System.out.println("Currency: " + order.getCurrency());
            
            // Step 3: Query order
            OrderResponse retrievedOrder = client.order.getOrderById(order.getId().toString());
            System.out.println("\n=== Order Retrieved ===");
            System.out.println("Current status: " + retrievedOrder.getStatus());
            
        } catch (IllegalArgumentException e) {
            System.err.println("Validation error: " + e.getMessage());
        } catch (RuntimeException e) {
            System.err.println("API error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Order Statuses

Orders can have different statuses:

• PENDING - Pending processing
• PROCESSING - In progress
• COMPLETED - Completed
• FAILED - Failed
• CANCELLED - Cancelled

Query status regularly:

OrderResponse order = client.order.getOrderById(orderId);

switch (order.getStatus()) {
    case "COMPLETED":
        System.out.println("✅ Order completed successfully");
        break;
    case "FAILED":
        System.out.println("❌ Order failed");
        break;
    case "PROCESSING":
        System.out.println("⏳ Order in progress...");
        break;
    default:
        System.out.println("Status: " + order.getStatus());
}

Error Handling

try {
    OrderResponse order = client.order.createPayoutOrder(orderInput);
} catch (IllegalArgumentException e) {
    // Validation error (invalid data)
    System.err.println("Validation error: " + e.getMessage());
} catch (RuntimeException e) {
    // API error (4xx, 5xx)
    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 to get the current exchange rate
2. Validate data for sender and beneficiary
3. Create order using the quotation ID
4. Query order periodically to check status
5. Handle statuses according to the result

Next Steps

• Examples - More usage examples
• Error Handling - Learn to handle errors correctly
• Advanced Topics - Advanced features