Recibir Pagos (PAYIN)

Aprende cómo aceptar pagos de clientes usando métodos de pago locales en toda América Latina.

¿Qué es PAYIN?

PAYIN es el tipo de orden utilizado para aceptar pagos de clientes en tu cuenta de saldo virtual.

Casos de Uso

Cómo Funciona

Flujo de Alto Nivel

Diagrama de Flujo Detallado

Países y Métodos de Pago Soportados

Colombia 🇨🇴

Aprende más sobre métodos de pago colombianos →

Brasil 🇧🇷

México 🇲🇽

Chile 🇨🇱

Argentina 🇦🇷

Prerequisitos

Antes de integrar órdenes PAYIN, asegúrate de tener:

Inicio Rápido

¿Quieres empezar de inmediato? Sigue nuestra guía de integración paso a paso:

O prueba el inicio rápido para un resumen más rápido:

Flujo de Pago Explicado

Proceso Paso a Paso

1. Autenticación

Obtén un token de acceso usando tus credenciales API.

1
const token = await authenticate(apiKey, secret);

2. Obtener Métodos de Pago Disponibles

Consulta qué métodos de pago están disponibles para el país del cliente.

1
const methods = await getPaymentMethods('CO', 'COP');
2
// Devuelve: PSE, NEQUI, etc.

3. Crear Contacto (Opcional pero Recomendado)

Almacena información del cliente para seguimiento y cumplimiento.

1
const contact = await createContact({
2
  email: 'cliente@ejemplo.com',
3
  fullName: 'Juan Pérez',
4
  country: 'CO'
5
});

4. Crear Orden PAYIN

Crea la orden de pago con monto y método de pago.

1
const order = await createPayinOrder({
2
  amount: 50000,
3
  currency: 'COP',
4
  paymentMethod: 'PSE',
5
  contactId: contact.id
6
});

5. Redirigir Cliente

Envía al cliente a la URL de pago para completar el pago.

1
window.location.href = order.paymentUrl;

6. Manejar Webhooks

Escucha eventos de webhook para saber cuándo el pago está completo.

1
// Webhook: order.completed
2
// -> Cumplir orden, enviar email de confirmación

Progresión de Estados de Orden

Comprender los estados de orden:

Conceptos Clave

URL de Pago

Cada orden PAYIN devuelve una paymentUrl:

1
{
2
  "paymentUrl": "https://checkout.koywe.com/pay/ord_abc123"
3
}

Esta URL:

• Es alojada por Koywe
• Proporciona una experiencia de pago segura
• Maneja la UI del método de pago
• Redirige de vuelta a tu successUrl o failedUrl

URLs de Éxito y Fallo

Especifica dónde redirigir a los clientes después del pago:

1
{
2
  "successUrl": "https://tusitio.com/pago/exito",
3
  "failedUrl": "https://tusitio.com/pago/fallo"
4
}

ID Externo (Idempotencia)

Usa externalId para vincular órdenes a tu sistema y prevenir duplicados:

1
{
2
  "externalId": "orden-12345"  // Tu ID de orden interno
3
}

Beneficios:

• Seguro para reintentar llamadas API fallidas
• Previene cargos duplicados
• Fácil reconciliación con tu base de datos

Patrones Comunes de Integración

Patrón 1: Checkout Simple

1
// 1. Usuario hace clic en "Pagar"
2
// 2. Crear orden
3
const order = await createPayinOrder({
4
  amount: cartTotal,
5
  currency: 'COP',
6
  paymentMethod: 'PSE'
7
});
8
// 3. Redirigir
9
window.location.href = order.paymentUrl;
10
// 4. Manejar webhook
11
// 5. Cumplir orden

Patrón 2: Selección de Método de Pago

1
// 1. Mostrar métodos disponibles
2
const methods = await getPaymentMethods(country, currency);
3
// 2. Usuario selecciona método
4
// 3. Crear orden con método seleccionado
5
const order = await createPayinOrder({
6
  amount: cartTotal,
7
  currency: 'COP',
8
  paymentMethod: userSelectedMethod
9
});
10
// 4. Redirigir y manejar webhook

Patrón 3: Cliente Almacenado

1
// 1. Verificar si el cliente existe
2
let contact = await findContact(email);
3
if (!contact) {
4
  contact = await createContact(customerData);
5
}
6
// 2. Crear orden vinculada al contacto
7
const order = await createPayinOrder({
8
  amount: cartTotal,
9
  contactId: contact.id,
10
  // ... otros campos
11
});
12
// 3. Rastrear historial de pagos por contacto

Próximos Pasos

Recursos Adicionales

• Conceptos Clave - Órdenes
• Webhooks Profundo
• Manejo de Errores
• Referencia API