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

$
curl -X GET 'https://api-sandbox.koywe.com/api/v1/payment-methods?countrySymbol=CO&currencySymbol=COP' \
>
  -H 'Authorization: Bearer TU_TOKEN'

1
async function createContact(token, orgId, merchantId, contactData) {
2
  const response = await axios.post(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
4
    {
5
      email: contactData.email,                    // Opcional pero recomendado
6
      phone: contactData.phone,                    // Opcional
7
      fullName: contactData.fullName,              // Requerido
8
      countrySymbol: contactData.countrySymbol,    // Requerido (ej., 'CO')
9
      documentType: contactData.documentType,      // Requerido (ej., 'CC')
10
      documentNumber: contactData.documentNumber,  // Requerido
11
      businessType: 'PERSON'                       // 'PERSON' o 'COMPANY'
12
    },
13
    {
14
      headers: { 
15
        'Authorization': `Bearer ${token}`,
16
        'Content-Type': 'application/json'
17
      }
18
    }
19
  );
20
  
21
  return response.data;
22
}
23
24
// Uso
25
const contact = await createContact(token, orgId, merchantId, {
26
  email: 'cliente@ejemplo.com',
27
  phone: '+573001234567',
28
  fullName: 'Juan Pérez',
29
  countrySymbol: 'CO',
30
  documentType: 'CC',  // ID colombiano
31
  documentNumber: '1234567890'
32
});
33
34
console.log('Contacto creado:', contact.id);

1
async function createPayinOrder(token, orgId, merchantId, orderData) {
2
  const response = await axios.post(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
4
    {
5
      type: 'PAYIN',                                // Tipo de orden
6
      originCurrencySymbol: orderData.currency,     // ej., 'COP'
7
      destinationCurrencySymbol: orderData.currency, // Misma que origen para PAYIN
8
      amountIn: orderData.amount,                   // Monto a cobrar
9
      description: orderData.description,           // Descripción visible para cliente
10
      externalId: orderData.externalId,             // Tu referencia interna (para idempotencia)
11
      contactId: orderData.contactId,               // Contacto del Paso 3 (opcional)
12
      paymentMethods: [                             // Al menos un método de pago requerido
13
        {
14
          method: orderData.paymentMethod,          // ej., 'PSE', 'PIX', 'SPEI'
15
          extra: orderData.extra                    // Datos adicionales (ej., banco para PSE)
16
        }
17
      ],
18
      successUrl: orderData.successUrl,             // Redirección después de éxito
19
      failedUrl: orderData.failedUrl                // Redirección después de fallo
20
    },
21
    {
22
      headers: { 
23
        'Authorization': `Bearer ${token}`,
24
        'Content-Type': 'application/json'
25
      }
26
    }
27
  );
28
  
29
  return response.data;
30
}
31
32
// Uso
33
const order = await createPayinOrder(token, orgId, merchantId, {
34
  currency: 'COP',
35
  amount: 50000,                        // 50,000 COP
36
  description: 'Pago por Orden #12345',
37
  externalId: `order-12345-${Date.now()}`,  // Único por intento
38
  contactId: contact.id,
39
  paymentMethod: 'PSE',
40
  extra: 'BANCOLOMBIA',                 // Selección de banco para PSE
41
  successUrl: 'https://tusitio.com/pago/exitoso',
42
  failedUrl: 'https://tusitio.com/pago/fallido'
43
});
44
45
console.log('ID de Orden:', order.id);
46
console.log('URL de Pago:', order.paymentUrl);
47
// Redirige al cliente a order.paymentUrl

1
// Redirección directa
2
window.location.href = order.paymentUrl;
3
4
// O abrir en nueva ventana
5
window.open(order.paymentUrl, '_blank');
6
7
// O devolver URL al frontend
8
res.json({ 
9
  orderId: order.id,
10
  paymentUrl: order.paymentUrl 
11
});

1
const express = require('express');
2
const crypto = require('crypto');
3
4
app.post('/webhooks/koywe', express.raw({type: 'application/json'}), async (req, res) => {
5
  // Convertir body raw a string una vez
6
  const rawBody = req.body.toString();
7
  
8
  // 1. Verificar firma de webhook
9
  const signature = req.headers['koywe-signature'];
10
  const secret = process.env.KOYWE_WEBHOOK_SECRET;
11
  
12
  const expectedSignature = crypto
13
    .createHmac('sha256', secret)
14
    .update(rawBody)
15
    .digest('hex');
16
  
17
  if (signature !== expectedSignature) {
18
    console.error('Firma de webhook inválida');
19
    return res.status(401).send('Firma inválida');
20
  }
21
  
22
  // 2. Parsear evento desde string
23
  const event = JSON.parse(rawBody);
24
  const eventId = event.id;
25
  
26
  // 3. Verificar duplicado (idempotencia)
27
  if (await isEventProcessed(eventId)) {
28
    return res.status(200).send('Ya procesado');
29
  }
30
  
31
  // 4. Manejar evento basado en tipo
32
  try {
33
    switch (event.type) {
34
      case 'order.created':
35
        console.log('Orden creada:', event.data.orderId);
36
        break;
37
        
38
      case 'order.pending':
39
        console.log('Orden pendiente:', event.data.orderId);
40
        await updateOrderStatus(event.data.externalId, 'pending');
41
        break;
42
        
43
      case 'order.processing':
44
        console.log('Pago en proceso:', event.data.orderId);
45
        await updateOrderStatus(event.data.externalId, 'processing');
46
        break;
47
        
48
      case 'order.paid':
49
        console.log('Pago confirmado:', event.data.orderId);
50
        await updateOrderStatus(event.data.externalId, 'paid');
51
        await sendConfirmationEmail(event.data.externalId);
52
        break;
53
        
54
      case 'order.completed':
55
        console.log('Fondos acreditados:', event.data.orderId);
56
        await updateOrderStatus(event.data.externalId, 'completed');
57
        // CUMPLIR LA ORDEN AQUÍ
58
        await fulfillOrder(event.data.externalId);
59
        await sendShippingNotification(event.data.externalId);
60
        break;
61
        
62
      case 'order.failed':
63
        console.log('Pago falló:', event.data.orderId);
64
        await updateOrderStatus(event.data.externalId, 'failed');
65
        await sendFailureNotification(event.data.externalId);
66
        break;
67
        
68
      case 'order.expired':
69
        console.log('Orden expiró:', event.data.orderId);
70
        await updateOrderStatus(event.data.externalId, 'expired');
71
        break;
72
        
73
      case 'order.cancelled':
74
        console.log('Orden cancelada:', event.data.orderId);
75
        await updateOrderStatus(event.data.externalId, 'cancelled');
76
        break;
77
    }
78
    
79
    // 5. Marcar evento como procesado
80
    await markEventProcessed(eventId);
81
    
82
    // 6. Responder rápidamente (< 5 segundos)
83
    res.status(200).send('OK');
84
    
85
  } catch (error) {
86
    console.error('Error procesando webhook:', error);
87
    // Aún devolver 200 para prevenir reintentos por errores de procesamiento
88
    res.status(200).send('OK');
89
    // Registrar error para revisión manual
90
    await logWebhookError(event, error);
91
  }
92
});