Koywe
En esta página

Inicio Rápido de 5 Minutos

Qué Construirás

Crea una orden PAYIN simple para aceptar un pago de un cliente. Este inicio rápido te pone en marcha sin profundizar en conceptos complejos.

Al final de esta guía, podrás:

  • Autenticarte con la API de Koywe
  • Crear una orden de pago
  • Rastrear el estado del pago

Requisitos Previos

Antes de comenzar, asegúrate de tener:

  • API Key y Secret (contacta a soporte@koywe.com si no los tienes)
  • ID de Organización
  • ID de Comercio
  • Una herramienta para hacer solicitudes HTTP (cURL, Postman o tu lenguaje de programación preferido)

Este inicio rápido usa el entorno sandbox. Todos los pagos son simulados y no se involucra dinero real.

Atajo: el CLI (≈ 30 segundos)

Si eres un agente de IA o simplemente quieres ver una orden de punta a punta, salta el recorrido HTTP y usa el CLI de Koywe. Tres comandos — login por navegador, elige una organización, corre un flujo guiado de orden:

Terminal
npx @koyweforest/cli init                              # login por navegador + auto-crear credenciales
npx @koyweforest/cli config set organizationId <org_id>
npx @koyweforest/cli flow order                        # interactivo: cotización → crear → esperar

flow order pide el tipo, la moneda, el monto y el método de pago, y luego encadena cotización + creación + polling de estado en un solo comando. 26 de los 142 comandos (los create y update) aceptan --schema para imprimir el esquema JSON completo del cuerpo de solicitud — ejecútalo antes de construir el payload en vez de adivinar campos.

Si prefieres llamar a la API directamente, sigue leyendo — el resto de la página recorre el mismo flujo con curl, Node y Python.

Paso 1: Autenticación

Primero, obtén un token de acceso usando tus credenciales API:

curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your_api_key",
    "secret": "your_secret"
  }'

Respuesta:

JSON
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Almacena este token de forma segura. Necesitarás incluirlo en todas las solicitudes posteriores como:
Authorization: Bearer TU_TOKEN

El token expira después de 1 hora. En producción, implementa lógica de actualización de token.

Paso 2: Crear un Contacto (Opcional)

Aunque es opcional, crear un contacto te ayuda a rastrear qué cliente realizó el pago:

async function createContact(token, orgId, merchantId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      email: 'cliente@ejemplo.com',
      phone: '+573001234567',
      firstName: 'Juan',
      lastName: 'Pérez',
      countrySymbol: 'CO',
      documentType: 'CED_CIU',
      documentNumber: '1234567890',
      businessType: 'PERSON',
      type: 'PERSON'
    },
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso
const contact = await createContact(token, 'tu_org_id', 'tu_merchant_id');
console.log('ID de Contacto:', contact.id);

Paso 3: Obtener una Cotización

Obtén una cotización de tasa de cambio para el pago (opcional pero recomendado para transparencia):

async function getQuote(token, orgId, merchantId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: 50000, // 50,000 COP
      orderType: 'PAYIN',
      executable: true
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso
const quote = await getQuote(token, 'tu_org_id', 'tu_merchant_id');
console.log('Cotización:', quote);

Paso 4: Crear Tu Primera Orden PAYIN

Ahora crea la orden de pago. Esto genera una URL de pago donde tu cliente puede completar el pago:

async function createPayinOrder(token, orgId, merchantId, contactId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYIN',                              // Tipo de orden: recibir pago
      originCurrencySymbol: 'COP',                // Moneda: Pesos Colombianos
      destinationCurrencySymbol: 'COP',           // Misma moneda (sin conversión)
      amountIn: 50000,                            // Monto: 50,000 COP
      description: 'Pago por Orden #12345',       // Descripción para el cliente
      externalId: `order-${Date.now()}`,          // Tu referencia interna
      contactId: contactId,                       // Cliente que está pagando
      paymentMethods: [
        {
          method: 'PSE',                                       // Método de pago: PSE (transferencia bancaria colombiana)
          extra: { bankAccount: { name: 'BANCOLOMBIA' } }      // Datos por método
        }
      ],
      successUrl: 'https://tusitio.com/pago/exitoso',  // Redirección después de éxito
      failedUrl: 'https://tusitio.com/pago/fallido'    // Redirección después de fallo
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso
const order = await createPayinOrder(token, 'tu_org_id', 'tu_merchant_id', contact.id);
console.log('Orden creada:', order.id);
console.log('URL de pago:', order.providedAction);

Respuesta:

JSON
{
  "id": "ord_abc123xyz",
  "type": "PAYIN",
  "status": "PENDING",
  "amountIn": 50000,
  "originCurrencySymbol": "COP",
  "destinationCurrencySymbol": "COP",
  "providedAction": "https://checkout.koywe.com/pay/ord_abc123xyz",
  "externalId": "order-1699999999",
  "description": "Pago por Orden #12345",
  "createdAt": "2025-11-13T10:00:00Z"
}

¡Éxito! Has creado tu primera orden de pago. La providedAction es donde debes redirigir a tu cliente para completar el pago.

Paso 5: Rastrear el Estado de la Orden

Puedes verificar el estado de la orden en cualquier momento:

async function getOrderStatus(token, orgId, merchantId, orderId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders/${orderId}`,
    {
      headers: { 
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  return response.data;
}
 
// Uso
const orderStatus = await getOrderStatus(token, 'tu_org_id', 'tu_merchant_id', order.id);
console.log('Estado de la orden:', orderStatus.status);
// Estados posibles: PENDING, PROCESSING, PAID, COMPLETED, FAILED, CANCELLED, EXPIRED

Flujo de Estados de la Orden:

Texto
PENDING → PROCESSING → PAID → COMPLETED
  • PENDING: Orden creada, esperando pago del cliente
  • PROCESSING: El pago se está procesando
  • PAID: Pago confirmado
  • COMPLETED: Fondos acreditados a tu saldo virtual

Ejemplo Completo de Extremo a Extremo

Aquí hay un ejemplo de trabajo completo que lo une todo:

const axios = require('axios');
 
const BASE_URL = 'https://api-sandbox.koywe.com/api/v1';
const ORG_ID = process.env.KOYWE_ORG_ID;
const MERCHANT_ID = process.env.KOYWE_MERCHANT_ID;
const API_KEY = process.env.KOYWE_API_KEY;
const SECRET = process.env.KOYWE_SECRET;
 
async function main() {
  try {
    // 1. Autenticar
    console.log('1. Autenticando...');
    const authResponse = await axios.post(`${BASE_URL}/auth/sign-in`, {
      apiKey: API_KEY,
      secret: SECRET
    });
    const token = authResponse.data.token;
    console.log('✓ Autenticado');
 
    // 2. Crear contacto
    console.log('\n2. Creando contacto...');
    const contactResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/contacts`,
      {
        email: 'cliente@ejemplo.com',
        phone: '+573001234567',
        firstName: 'Juan',
        lastName: 'Pérez',
        countrySymbol: 'CO',
        documentType: 'CED_CIU',
        documentNumber: '1234567890',
        businessType: 'PERSON',
        type: 'PERSON'
      },
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const contactId = contactResponse.data.id;
    console.log('✓ Contacto creado:', contactId);
 
    // 3. Crear orden PAYIN
    console.log('\n3. Creando orden de pago...');
    const orderResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders`,
      {
        type: 'PAYIN',
        originCurrencySymbol: 'COP',
        destinationCurrencySymbol: 'COP',
        amountIn: 50000,
        description: 'Pago por Orden #12345',
        externalId: `order-${Date.now()}`,
        contactId: contactId,
        paymentMethods: [{ method: 'PSE', extra: { bankAccount: { name: 'BANCOLOMBIA' } } }],
        successUrl: 'https://tusitio.com/exitoso',
        failedUrl: 'https://tusitio.com/fallido'
      },
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const order = orderResponse.data;
    console.log('✓ Orden creada:', order.id);
    console.log('✓ URL de pago:', order.providedAction);
 
    // 4. Verificar estado de la orden
    console.log('\n4. Verificando estado de la orden...');
    const statusResponse = await axios.get(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders/${order.id}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    console.log('✓ Estado actual:', statusResponse.data.status);
 
    console.log('\n✅ ¡Éxito! Orden de pago creada.');
    console.log('👉 Redirige a tu cliente a:', order.providedAction);
 
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
  }
}
 
main();

Próximos Pasos

¡Felicitaciones! Has creado exitosamente tu primera orden de pago. Aquí está lo que puedes explorar a continuación:

Conceptos Clave

Comprende organizaciones, comercios, cuentas virtuales y tipos de órdenes

Integración Completa

Integración completa lista para producción con webhooks y manejo de errores

Guía de Pruebas

Prueba diferentes escenarios de pago en el entorno sandbox

Configurar Webhooks

Recibe notificaciones en tiempo real cuando los pagos se completen

¿Necesitas Ayuda?