Guía de Órdenes

Esta guía te muestra cómo crear y gestionar órdenes de pago usando el SDK de Retorna.

Crear una Orden de Pago

Crea una nueva orden de pago. Primero necesitas una cotización válida:

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

// Primero, crea una cotización
CreateQuoteInput quoteInput = new CreateQuoteInput(
    "USD", "CO", "COP", 100.0, "BANK_TRANSFER", AmountType.SOURCE
);
QuoteResponse quote = client.quotation.createQuote(quoteInput);

// Luego, crea la orden usando el ID de la cotización
PaymentInstructions instructions = new PaymentInstructions(
    "Banco de Ejemplo",      // bankName
    "1234567890",            // accountNumber
    "CHECKING",              // accountType
    "+573001234567",         // phoneNumber
    "001"                    // branchId (opcional)
);

CreateOrderInput orderInput = new CreateOrderInput(
    quote.getId().intValue(),        // pogQuotationId: ID de la cotización
    "ORD-2024-001",                  // externalId: ID externo único
    "BANK_TRANSFER",                  // payoutTypePlatformName
    "Juan",                           // senderNames
    "Pérez",                          // senderLastNames
    "[email protected]",         // senderEmail
    "+573001234567",                  // senderPhone
    "1234567890",                     // senderDocumentId
    "CC",                             // senderDocumentType
    "US",                             // senderCountry
    "US",                             // sourceCountry
    "María",                          // beneficiaryNames
    "García",                         // beneficiaryLastNames
    "[email protected]",       // beneficiaryEmail
    "+573009876543",                  // beneficiaryPhone
    "9876543210",                     // beneficiaryDocumentId
    "CC",                             // beneficiaryDocumentType
    instructions,                     // paymentInstructions
    PaymentPurpose.FAMILY_SUPPORT     // paymentPurpose
);

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

System.out.println("Orden creada: " + order.getId());
System.out.println("Estado: " + order.getStatus());
System.out.println("Monto: " + order.getAmount());

Parámetros de Orden

CreateOrderInput

Información de Cotización

• pogQuotationId (Integer): ID de la cotización creada previamente

Identificación Externa

• externalId (String): ID único externo para tu referencia

Plataforma de Pago

• payoutTypePlatformName (String): Nombre de la plataforma (ej: "BANK_TRANSFER")

Información del Remitente

• senderNames (String): Nombres del remitente
• senderLastNames (String): Apellidos del remitente
• senderEmail (String): Email del remitente
• senderPhone (String): Teléfono del remitente
• senderDocumentId (String): Número de documento
• senderDocumentType (String): Tipo de documento (CC, CE, PASSPORT, etc.)
• senderCountry (String): Código de país del remitente
• sourceCountry (String): Código de país origen

Información del Beneficiario

• beneficiaryNames (String): Nombres del beneficiario
• beneficiaryLastNames (String): Apellidos del beneficiario
• beneficiaryEmail (String): Email del beneficiario
• beneficiaryPhone (String): Teléfono del beneficiario
• beneficiaryDocumentId (String): Número de documento
• beneficiaryDocumentType (String): Tipo de documento

Instrucciones de Pago

• paymentInstructions (PaymentInstructions): Instrucciones específicas de pago
• paymentPurpose (PaymentPurpose): Propósito del pago

PaymentInstructions

Depende de la plataforma, pero generalmente incluye:

PaymentInstructions instructions = new PaymentInstructions(
    "Banco de Ejemplo",      // bankName: Nombre del banco
    "1234567890",            // accountNumber: Número de cuenta
    "CHECKING",              // accountType: Tipo de cuenta (CHECKING, SAVINGS)
    "+573001234567",         // phoneNumber: Teléfono
    "001"                    // branchId: ID de sucursal (opcional)
);

PaymentPurpose

Propósitos disponibles:

• FAMILY_SUPPORT - Apoyo familiar
• BUSINESS_PAYMENT - Pago comercial
• SALARY - Salario
• OTHER - Otro

Consultar una Orden

Obtén los detalles de una orden existente:

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

System.out.println("ID: " + order.getId());
System.out.println("Estado: " + order.getStatus());
System.out.println("Monto: " + order.getAmount());
System.out.println("Moneda: " + order.getCurrency());
System.out.println("Fecha creación: " + order.getCreatedAt());

Con Parámetros Opcionales

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);

Validación Automática

El SDK valida automáticamente los datos según la plataforma de pago seleccionada. Cada país tiene validadores específicos:

• Argentina: Valida formato de CUIT, CBU, etc.
• Colombia: Valida formato de cédula, cuenta bancaria, etc.
• Perú: Valida formato de DNI, cuenta interbancaria, etc.
• España: Valida formato de NIE/NIF, IBAN, etc.
• USA: Valida formato de SSN, cuenta bancaria, etc.
• Venezuela: Valida formato de cédula, cuenta bancaria, etc.

Si la validación falla, recibirás una excepción antes de enviar la solicitud a la API.

Ejemplo Completo

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 {
            // Paso 1: Crear cotización
            CreateQuoteInput quoteInput = new CreateQuoteInput(
                "USD", "CO", "COP", 100.0, "BANK_TRANSFER", AmountType.SOURCE
            );
            QuoteResponse quote = client.quotation.createQuote(quoteInput);
            System.out.println("Cotización creada: " + quote.getId());
            
            // Paso 2: Crear orden
            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",
                "[email protected]",
                "+573001234567",
                "1234567890",
                "CC",
                "US",
                "US",
                "María",
                "García",
                "[email protected]",
                "+573009876543",
                "9876543210",
                "CC",
                instructions,
                PaymentPurpose.FAMILY_SUPPORT
            );
            
            OrderResponse order = client.order.createPayoutOrder(orderInput);
            
            System.out.println("\n=== Orden Creada ===");
            System.out.println("ID: " + order.getId());
            System.out.println("Estado: " + order.getStatus());
            System.out.println("Monto: " + order.getAmount());
            System.out.println("Moneda: " + order.getCurrency());
            
            // Paso 3: Consultar orden
            OrderResponse retrievedOrder = client.order.getOrderById(order.getId().toString());
            System.out.println("\n=== Orden Consultada ===");
            System.out.println("Estado actual: " + retrievedOrder.getStatus());
            
        } catch (IllegalArgumentException e) {
            System.err.println("Error de validación: " + e.getMessage());
        } catch (RuntimeException e) {
            System.err.println("Error de API: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Estados de Orden

Las órdenes pueden tener diferentes estados:

• PENDING - Pendiente de procesamiento
• PROCESSING - En proceso
• COMPLETED - Completada
• FAILED - Fallida
• CANCELLED - Cancelada

Consulta el estado regularmente:

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

switch (order.getStatus()) {
    case "COMPLETED":
        System.out.println("✅ Orden completada exitosamente");
        break;
    case "FAILED":
        System.out.println("❌ Orden fallida");
        break;
    case "PROCESSING":
        System.out.println("⏳ Orden en proceso...");
        break;
    default:
        System.out.println("Estado: " + order.getStatus());
}

Manejo de Errores

try {
    OrderResponse order = client.order.createPayoutOrder(orderInput);
} catch (IllegalArgumentException e) {
    // Error de validación (datos inválidos)
    System.err.println("Error de validación: " + e.getMessage());
} catch (RuntimeException e) {
    // Error de API (4xx, 5xx)
    System.err.println("Error de API: " + e.getMessage());
} catch (Exception e) {
    // Error general
    System.err.println("Error: " + e.getMessage());
    e.printStackTrace();
}

Flujo Recomendado

1. Crear cotización para obtener el tipo de cambio actual
2. Validar datos del remitente y beneficiario
3. Crear orden usando el ID de la cotización
4. Consultar orden periódicamente para verificar el estado
5. Manejar estados según el resultado

Siguiente Paso

• Ejemplos - Más ejemplos de uso
• Manejo de Errores - Aprende a manejar errores correctamente
• Temas Avanzados - Funcionalidades avanzadas