🧪 Pruebas en Sandbox

Guía completa para probar todos los escenarios de pago

Pruebas en Sandbox

El entorno sandbox de Koywe te permite probar todos los flujos de pago con transacciones simuladas antes de ir en vivo.

Entorno Sandbox

URL Base

Todas las solicitudes API de sandbox usan:

https://api-sandbox.koywe.com

Obtener Credenciales de Prueba

Contacta a soporte@koywe.com para recibir:

  • API Key de Sandbox
  • Secret de Sandbox
  • ID de Organización
  • ID de Comercio

Sandbox vs Producción: Las credenciales de sandbox están completamente separadas de producción. No se involucra dinero real en las pruebas de sandbox.


Métodos de Pago de Prueba por País

Colombia (COP) 🇨🇴

PSE (Pagos Seguros en Línea)

Bancos de Prueba:

  • BANCOLOMBIA
  • DAVIVIENDA
  • BOGOTA
  • OCCIDENTE

Uso:

1{
2 "method": "PSE",
3 "extra": "BANCOLOMBIA" // Cualquier banco de prueba
4}

Comportamiento:

  • El enlace de pago es completamente funcional en sandbox
  • Sigue el proceso de pago simulado
  • Puedes elegir éxito o fallo del pago durante el flujo
  • Permite probar la experiencia completa del usuario

Nequi

Uso:

1{
2 "method": "NEQUI"
3}

Comportamiento:

  • Genera un código QR de prueba
  • Después de escanear el código QR, recibirás opciones para éxito o fallo del pago
  • Simula la experiencia completa de pago Nequi

Brasil (BRL) 🇧🇷

PIX Estático

Uso:

1{
2 "method": "PIX_STATIC"
3}

Comportamiento:

  • Genera un código QR de prueba
  • Después de escanear el código QR, recibirás opciones para éxito o fallo del pago
  • Simula la experiencia completa de pago PIX

PIX Dinámico

Uso:

1{
2 "method": "PIX_DYNAMIC"
3}

Comportamiento:

  • Genera un código QR de prueba
  • Después de escanear el código QR, recibirás opciones para éxito o fallo del pago
  • Similar a PIX_STATIC con opciones de prueba interactivas

México (MXN) 🇲🇽

SPEI

Uso:

1{
2 "method": "SPEI"
3}

Comportamiento:

  • Proporciona detalles de cuenta bancaria de prueba
  • Se completa automáticamente después de la creación de la orden
  • Simula confirmación de transferencia bancaria

Tarjetas

Números de Tarjeta de Prueba:

  • Éxito: 4242424242424242
  • Rechazada: 4000000000000002
  • Fondos Insuficientes: 4000000000009995

Uso:

1{
2 "method": "CARD"
3}

Chile (CLP) 🇨🇱

Khipu

Uso:

1{
2 "method": "KHIPU"
3}

Comportamiento:

  • El enlace de pago es completamente funcional en sandbox
  • Sigue el proceso de pago simulado
  • Puedes elegir éxito o fallo del pago durante el flujo
  • Permite probar la experiencia completa del usuario

Argentina (ARS) 🇦🇷

Múltiples Métodos Locales

Uso:

1{
2 "method": "KHIPU" // También funciona para Argentina
3}

Comportamiento:

  • El enlace de pago es completamente funcional en sandbox
  • Puedes elegir éxito o fallo del pago durante el flujo

Escenarios de Prueba

Pruebas Interactivas: La mayoría de métodos de pago (PSE, Khipu) proporcionan enlaces de pago funcionales donde puedes seguir el proceso de pago simulado y elegir éxito o fallo. Los métodos basados en QR (PIX, Nequi) te dan opciones después de escanear el código.

Flujo de Pago Exitoso

Prueba un pago exitoso de extremo a extremo:

Node.js
1async function testSuccessfulPayment() {
2 // Cualquier monto tendrá éxito en sandbox
3 const order = await createPayinOrder(token, orgId, merchantId, {
4 amount: 50000,
5 currency: 'COP',
6 paymentMethod: 'PSE',
7 bank: 'BANCOLOMBIA'
8 });
9
10 console.log('Orden creada:', order.id);
11 console.log('Estado:', order.status); // "PENDING"
12 console.log('URL de Pago:', order.paymentUrl);
13
14 // En sandbox, la orden se completa automáticamente
15 // Espera unos segundos y verifica el estado
16 await sleep(5000);
17
18 const updated = await getOrderStatus(token, orgId, merchantId, order.id);
19 console.log('Estado actualizado:', updated.status); // "COMPLETED"
20}

Flujo esperado:

PENDING → PROCESSING → PAID → COMPLETED

Escenario de Pago Fallido

Prueba el manejo de fallo de pago:

Usa el monto especial de prueba 666 para simular un pago fallido:

Node.js
1async function testFailedPayment() {
2 const order = await createPayinOrder(token, orgId, merchantId, {
3 amount: 666, // Monto especial de prueba para fallo
4 currency: 'COP',
5 paymentMethod: 'PSE',
6 bank: 'BANCOLOMBIA'
7 });
8
9 console.log('Orden creada:', order.id);
10
11 // Espera el procesamiento
12 await sleep(3000);
13
14 const updated = await getOrderStatus(token, orgId, merchantId, order.id);
15 console.log('Estado:', updated.status); // "FAILED"
16 console.log('Error:', updated.errorMessage);
17}

Flujo esperado:

PENDING → PROCESSING → FAILED

Pago Expirado

Prueba la expiración de orden:

Node.js
1async function testExpiredPayment() {
2 // Establecer dueDate en el pasado
3 const pastDate = new Date();
4 pastDate.setHours(pastDate.getHours() - 1);
5
6 const order = await createPayinOrder(token, orgId, merchantId, {
7 amount: 50000,
8 currency: 'COP',
9 paymentMethod: 'PSE',
10 bank: 'BANCOLOMBIA',
11 dueDate: pastDate.toISOString()
12 });
13
14 console.log('Estado:', order.status); // "EXPIRED"
15}

Prueba la experiencia completa de checkout de marca Koywe:

PAYMENT_LINK es perfecto para e-commerce! Sin contacto o método de pago necesario - solo crea un enlace y compártelo. El cliente ingresa sus propios datos y selecciona su método de pago en el checkout de Koywe.

1async function testPaymentLink() {
2 // Crear enlace de pago - ¡sin contacto o método de pago necesario!
3 const order = await axios.post(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
5 {
6 type: 'PAYMENT_LINK',
7 originCurrencySymbol: 'COP',
8 destinationCurrencySymbol: 'COP',
9 amountIn: 50000,
10 description: 'Factura de Prueba #123 - Diseño Web',
11 externalId: `test-invoice-${Date.now()}`
12 },
13 { headers: { 'Authorization': `Bearer ${token}` } }
14 );
15
16 console.log('✓ Enlace de pago creado:', order.data.id);
17 console.log('📧 Comparte este enlace:', order.data.paymentUrl);
18 console.log('');
19 console.log('El cliente:');
20 console.log(' 1. Abre el enlace');
21 console.log(' 2. Ve checkout de marca Koywe');
22 console.log(' 3. Ingresa su información personal');
23 console.log(' 4. Selecciona método de pago (PSE, PIX, Nequi, etc.)');
24 console.log(' 5. Completa el pago');
25
26 // Simular compartir vía email, WhatsApp o código QR
27 return order.data;
28}
29
30// Uso
31const link = await testPaymentLink();
32
33// Abre la URL de pago en un navegador para probar el flujo completo de checkout
34console.log('\n🌐 Abre esta URL para probar:', link.paymentUrl);

Probando el flujo de checkout:

  1. Crea el enlace de pago usando el código anterior
  2. Copia la paymentUrl
  3. Ábrela en tu navegador
  4. Verás la página de checkout de marca Koywe
  5. Completa información de cliente de prueba
  6. Selecciona un método de pago
  7. Completa el pago simulado (elige éxito o fallo)
  8. Verifica que se reciba la notificación webhook

Caso de Uso: PAYMENT_LINK es ideal para:

  • Páginas de checkout e-commerce
  • Solicitudes de pago de facturas
  • Enlaces de pago vía email/WhatsApp
  • Pagos con código QR
  • Colecciones de pago rápidas sin almacenar datos del cliente

Probar Webhooks

Configurar Endpoint de Webhook

Usa herramientas de prueba de webhooks:

  1. webhook.site - URL de webhook instantánea
  2. ngrok - Túnel a localhost
  3. RequestBin - Inspector de webhooks

Usar webhook.site

1

Obtener URL de webhook

Visita webhook.site y copia tu URL única

2

Crear orden con webhook

1const order = await createPayinOrder(token, orgId, merchantId, {
2 amount: 50000,
3 webhookUrl: 'https://webhook.site/tu-id-unico'
4});
3

Ver webhooks

Regresa a webhook.site para ver eventos de webhook en tiempo real

Eventos de Webhook Esperados

Para un PAYIN exitoso:

  1. order.created - Orden es creada
  2. order.pending - Esperando pago
  3. order.processing - Pago siendo procesado
  4. order.paid - Pago confirmado
  5. order.completed - Fondos acreditados

Ejemplo de Payload de Webhook

1{
2 "id": "evt_abc123",
3 "type": "order.completed",
4 "version": "v1",
5 "occurred_at": "2025-11-13T15:30:00Z",
6 "source": "koywe.api",
7 "environment": "sandbox",
8 "organization_id": "org_xyz",
9 "merchant_id": "mrc_abc",
10 "data": {
11 "orderId": "ord_123456",
12 "type": "PAYIN",
13 "status": "COMPLETED",
14 "amountIn": 50000,
15 "currencySymbol": "COP"
16 }
17}

Datos de Prueba

Contactos de Prueba

Usa estos números de documento de prueba (todos válidos en sandbox):

Colombia

1{
2 "documentType": "CC",
3 "documentNumber": "1234567890",
4 "fullName": "Juan Pérez Prueba"
5}

Brasil

1{
2 "documentType": "CPF",
3 "documentNumber": "12345678900",
4 "fullName": "Maria Silva Prueba"
5}

México

1{
2 "documentType": "RFC",
3 "documentNumber": "XAXX010101000",
4 "fullName": "Pedro García Prueba"
5}

Chile

1{
2 "documentType": "RUT",
3 "documentNumber": "11111111-1",
4 "fullName": "Ana López Prueba"
5}

Cuentas Bancarias de Prueba

Para pruebas de PAYOUT:

Colombia

1{
2 "bankCode": "BANCOLOMBIA",
3 "accountNumber": "1234567890",
4 "accountType": "savings",
5 "currencySymbol": "COP"
6}

Brasil

1{
2 "bankCode": "BANCO_DO_BRASIL",
3 "accountNumber": "12345678",
4 "accountType": "checking",
5 "currencySymbol": "BRL"
6}

México

1{
2 "bankCode": "BBVA_MEXICO",
3 "accountNumber": "012345678901234567",
4 "accountType": "checking",
5 "currencySymbol": "MXN"
6}

Chile

1{
2 "bankCode": "BANCO_CHILE",
3 "accountNumber": "12345678",
4 "accountType": "checking",
5 "currencySymbol": "CLP"
6}

Probar Operaciones Cripto

Selección Automática de Red de Prueba

Nombres de Red de Producción en Sandbox: Al usar nombres de red de producción como ETHEREUM, POLYGON o BSC en sandbox, el sistema automáticamente redirige a redes de prueba (Sepolia, Amoy, BSC Testnet respectivamente). No necesitas especificar nombres de testnet explícitamente.

Redes de Prueba

Sandbox usa automáticamente estas testnets:

Red de ProducciónTestnet en SandboxActivos Soportados
ETHEREUMSepoliaETH, USDC, USDT
POLYGONAmoyMATIC, USDC
BSCBSC TestnetBNB, USDC

Ejemplo: Especifica "network": "POLYGON" en tu solicitud, y sandbox usará Amoy automáticamente.

Dirección de Billetera de Prueba

Usa esta dirección para recibir cripto de prueba:

0x0000000000000000000000000000000000000000

Nunca uses direcciones de producción en sandbox - Siempre usa direcciones de prueba/quema como la dirección cero arriba.

Prueba ONRAMP

Node.js
1async function testOnramp() {
2 // Crear billetera cripto (o usar existente)
3 const wallet = await createCryptoWallet(token, orgId, merchantId, {
4 address: '0x0000000000000000000000000000000000000000',
5 network: 'ETHEREUM' // Usa Sepolia automáticamente en sandbox
6 });
7
8 // Comprar USDC con COP
9 const order = await createOrder(token, orgId, merchantId, {
10 type: 'ONRAMP',
11 originCurrencySymbol: 'COP',
12 destinationCurrencySymbol: 'USDC',
13 amountIn: 50000,
14 destinationAccountId: wallet.id
15 });
16
17 console.log('Orden ONRAMP:', order.id);
18 // En sandbox, cripto es "enviado" a dirección de prueba
19}

Prueba OFFRAMP

Node.js
1async function testOfframp() {
2 // Vender USDC por COP
3 const order = await createOrder(token, orgId, merchantId, {
4 type: 'OFFRAMP',
5 originCurrencySymbol: 'USDC',
6 destinationCurrencySymbol: 'COP',
7 amountIn: 10 // 10 USDC
8 });
9
10 console.log('Orden OFFRAMP:', order.id);
11 // En sandbox, orden se completa automáticamente
12 // Fiat se acredita a cuenta virtual
13}

Límites de Tasa

El entorno sandbox tiene los siguientes límites:

Tipo de LímiteValor
Solicitudes por minuto100
Solicitudes por hora1,000
Órdenes por día10,000

Encabezados de límite de tasa están incluidos en todas las respuestas:

  • X-RateLimit-Limit: Total de solicitudes permitidas
  • X-RateLimit-Remaining: Solicitudes restantes
  • X-RateLimit-Reset: Timestamp Unix cuando se reinicia el límite

Mejores Prácticas de Prueba

Prueba Todos los Tipos de Orden

Prueba cada tipo de orden:

  • ✅ PAYIN con diferentes métodos de pago
  • ✅ PAYOUT a diferentes países
  • ✅ BALANCE_TRANSFER entre monedas
  • ✅ ONRAMP para compras de cripto
  • ✅ OFFRAMP para ventas de cripto
  • ✅ PAYMENT_LINK con vencimiento

Prueba Escenarios de Error

Prueba manejo de errores:

  • ✅ Credenciales API inválidas
  • ✅ Saldo insuficiente para PAYOUT
  • ✅ Detalles de cuenta bancaria inválidos
  • ✅ Cotizaciones expiradas
  • ✅ Pagos fallidos (monto: 666)
  • ✅ Verificación de firma de webhook

Prueba Idempotencia

Node.js
1async function testIdempotency() {
2 const externalId = `test-order-${Date.now()}`;
3
4 // Crear orden
5 const order1 = await createPayinOrder(token, orgId, merchantId, {
6 amount: 50000,
7 externalId: externalId
8 });
9
10 // Intentar crear la misma orden nuevamente
11 const order2 = await createPayinOrder(token, orgId, merchantId, {
12 amount: 50000,
13 externalId: externalId // Mismo externalId
14 });
15
16 // Debería devolver la misma orden
17 console.log(order1.id === order2.id); // true
18}

Flujos de Trabajo de Prueba Comunes

Flujo de Checkout E-Commerce

Node.js
1async function testCheckoutFlow() {
2 console.log('1. Cliente agrega items al carrito...');
3 const cartTotal = 50000; // 50,000 COP
4
5 console.log('2. Cliente procede al checkout...');
6 const contact = await createContact(token, orgId, merchantId, {
7 email: 'prueba@ejemplo.com',
8 fullName: 'Cliente Prueba',
9 country: 'CO',
10 documentType: 'CC',
11 documentNumber: '1234567890'
12 });
13
14 console.log('3. Obtener métodos de pago...');
15 const methods = await getPaymentMethods('CO', 'COP');
16
17 console.log('4. Crear orden de pago...');
18 const order = await createPayinOrder(token, orgId, merchantId, {
19 amount: cartTotal,
20 currency: 'COP',
21 contactId: contact.id,
22 paymentMethod: 'PSE',
23 bank: 'BANCOLOMBIA',
24 externalId: `cart-${Date.now()}`
25 });
26
27 console.log('5. Redirigir cliente al pago...');
28 console.log('URL de Pago:', order.paymentUrl);
29
30 console.log('6. Esperar confirmación por webhook...');
31 // En producción, el manejador de webhook procesa esto
32 await sleep(5000);
33
34 console.log('7. Verificar orden completada...');
35 const completed = await getOrderStatus(token, orgId, merchantId, order.id);
36 console.log('Estado final:', completed.status); // "COMPLETED"
37
38 console.log('8. Cumplir orden...');
39 console.log('✅ Flujo de checkout de prueba completo!');
40}

Pasar a Producción

Cuando estés listo para ir en vivo:

1

Solicitar Credenciales de Producción

Contacta a soporte@koywe.com para credenciales de producción API key y secret

2

Actualizar URL Base

Cambiar de sandbox a producción:

1// Sandbox
2const BASE_URL = 'https://api-sandbox.koywe.com';
3
4// Producción
5const BASE_URL = 'https://api.koywe.com';
3

Actualizar Credenciales

Reemplaza credenciales de sandbox con credenciales de producción en tus variables de entorno

4

Actualizar URLs de Webhook

Cambiar endpoints de webhook de URLs de prueba a URLs de producción

5

Probar con Montos Pequeños

Comienza con transacciones reales pequeñas para verificar que todo funciona

6

Monitorear de Cerca

Observa tus primeras transacciones de producción cuidadosamente

7

Configurar Monitoreo

Implementa logging, alertas y monitoreo para producción

Lista de Verificación de Producción

  • Credenciales de producción API obtenidas
  • URL base actualizada a producción
  • URLs de webhook apuntando a servidores de producción
  • Verificación de firma de webhook implementada
  • Manejo de errores probado
  • Logging y monitoreo configurado
  • Transacción de prueba pequeña exitosa
  • Equipo capacitado en procesos de producción

¿Necesitas Ayuda?