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:


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"
  }'


const axios = require('axios');
 
async function authenticate() {
  const response = await axios.post(
    'https://api-sandbox.koywe.com/api/v1/auth/sign-in',
    {
      apiKey: process.env.KOYWE_API_KEY,
      secret: process.env.KOYWE_SECRET
    }
  );
  
  return response.data.token;
}
 
// Uso
const token = await authenticate();
console.log('Token:', token);


import requests
import os
 
def authenticate():
    response = requests.post(
        'https://api-sandbox.koywe.com/api/v1/auth/sign-in',
        json={
            'apiKey': os.environ['KOYWE_API_KEY'],
            'secret': os.environ['KOYWE_SECRET']
        }
    )
    
    return response.json()['token']
 
# Uso
token = authenticate()
print(f'Token: {token}')

Respuesta:


{
  "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',
      fullName: 'Juan Pérez',
      countrySymbol: 'CO',
      documentType: 'CC',
      documentNumber: '1234567890',
      businessType: '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);


def create_contact(token, org_id, merchant_id):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts',
        json={
            'email': 'cliente@ejemplo.com',
            'phone': '+573001234567',
            'fullName': 'Juan Pérez',
            'countrySymbol': 'CO',
            'documentType': 'CC',
            'documentNumber': '1234567890',
            'businessType': 'PERSON'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso
contact = create_contact(token, 'tu_org_id', 'tu_merchant_id')
print(f"ID de Contacto: {contact['id']}")


curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/contacts' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "cliente@ejemplo.com",
    "phone": "+573001234567",
    "fullName": "Juan Pérez",
    "countrySymbol": "CO",
    "documentType": "CC",
    "documentNumber": "1234567890",
    "businessType": "PERSON"
  }'

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
      type: 'PAYIN'
    },
    {
      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);


def get_quote(token, org_id, merchant_id):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/quotes',
        json={
            'originCurrencySymbol': 'COP',
            'destinationCurrencySymbol': 'COP',
            'amountIn': 50000,  # 50,000 COP
            'type': 'PAYIN'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso
quote = get_quote(token, 'tu_org_id', 'tu_merchant_id')
print(f"Cotización: {quote}")


curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/quotes' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "originCurrencySymbol": "COP",
    "destinationCurrencySymbol": "COP",
    "amountIn": 50000,
    "type": "PAYIN"
  }'

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


def create_payin_order(token, org_id, merchant_id, contact_id):
    import time
    
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/orders',
        json={
            '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': f'order-{int(time.time())}',   # Tu referencia interna
            'contactId': contact_id,                      # Cliente que está pagando
            'paymentMethods': [
                {
                    'method': 'PSE',                      # Método de pago: PSE
                    'extra': 'BANCOLOMBIA'                # Banco específico
                }
            ],
            'successUrl': 'https://tusitio.com/pago/exitoso',
            'failedUrl': 'https://tusitio.com/pago/fallido'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso
order = create_payin_order(token, 'tu_org_id', 'tu_merchant_id', contact['id'])
print(f"Orden creada: {order['id']}")
print(f"URL de pago: {order['paymentUrl']}")


curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/orders' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PAYIN",
    "originCurrencySymbol": "COP",
    "destinationCurrencySymbol": "COP",
    "amountIn": 50000,
    "description": "Pago por Orden #12345",
    "externalId": "order-1699999999",
    "contactId": "CONTACT_ID_DEL_PASO_2",
    "paymentMethods": [
      {
        "method": "PSE",
        "extra": { "bankAccount": { "name": "BANCOLOMBIA" } }
      }
    ],
    "successUrl": "https://tusitio.com/pago/exitoso",
    "failedUrl": "https://tusitio.com/pago/fallido"
  }'

Respuesta:


{
  "id": "ord_abc123xyz",
  "type": "PAYIN",
  "status": "PENDING",
  "amountIn": 50000,
  "originCurrencySymbol": "COP",
  "destinationCurrencySymbol": "COP",
  "paymentUrl": "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 paymentUrl 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


def get_order_status(token, org_id, merchant_id, order_id):
    response = requests.get(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/orders/{order_id}',
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return response.json()
 
# Uso
order_status = get_order_status(token, 'tu_org_id', 'tu_merchant_id', order['id'])
print(f"Estado de la orden: {order_status['status']}")
# Estados posibles: PENDING, PROCESSING, PAID, COMPLETED, FAILED, CANCELLED, EXPIRED


curl -X GET 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/orders/ORDER_ID' \
  -H 'Authorization: Bearer TU_TOKEN'

Flujo de Estados de la Orden:


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',
        fullName: 'Juan Pérez',
        countrySymbol: 'CO',
        documentType: 'CC',
        documentNumber: '1234567890',
        businessType: '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.paymentUrl);
 
    // 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.paymentUrl);
 
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
  }
}
 
main();


import requests
import os
import time
 
BASE_URL = 'https://api-sandbox.koywe.com/api/v1'
ORG_ID = os.environ['KOYWE_ORG_ID']
MERCHANT_ID = os.environ['KOYWE_MERCHANT_ID']
API_KEY = os.environ['KOYWE_API_KEY']
SECRET = os.environ['KOYWE_SECRET']
 
def main():
    try:
        # 1. Autenticar
        print('1. Autenticando...')
        auth_response = requests.post(
            f'{BASE_URL}/auth/sign-in',
            json={'apiKey': API_KEY, 'secret': SECRET}
        )
        auth_response.raise_for_status()
        token = auth_response.json()['token']
        print('✓ Autenticado')
 
        headers = {'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'}
 
        # 2. Crear contacto
        print('\n2. Creando contacto...')
        contact_response = requests.post(
            f'{BASE_URL}/organizations/{ORG_ID}/merchants/{MERCHANT_ID}/contacts',
            json={
                'email': 'cliente@ejemplo.com',
                'phone': '+573001234567',
                'fullName': 'Juan Pérez',
                'countrySymbol': 'CO',
                'documentType': 'CC',
                'documentNumber': '1234567890',
                'businessType': 'PERSON'
            },
            headers=headers
        )
        contact_response.raise_for_status()
        contact_id = contact_response.json()['id']
        print(f'✓ Contacto creado: {contact_id}')
 
        # 3. Crear orden PAYIN
        print('\n3. Creando orden de pago...')
        order_response = requests.post(
            f'{BASE_URL}/organizations/{ORG_ID}/merchants/{MERCHANT_ID}/orders',
            json={
                'type': 'PAYIN',
                'originCurrencySymbol': 'COP',
                'destinationCurrencySymbol': 'COP',
                'amountIn': 50000,
                'description': 'Pago por Orden #12345',
                'externalId': f'order-{int(time.time())}',
                'contactId': contact_id,
                'paymentMethods': [{'method': 'PSE', 'extra': 'BANCOLOMBIA'}],
                'successUrl': 'https://tusitio.com/exitoso',
                'failedUrl': 'https://tusitio.com/fallido'
            },
            headers=headers
        )
        order_response.raise_for_status()
        order = order_response.json()
        print(f'✓ Orden creada: {order["id"]}')
        print(f'✓ URL de pago: {order["paymentUrl"]}')
 
        # 4. Verificar estado de la orden
        print('\n4. Verificando estado de la orden...')
        status_response = requests.get(
            f'{BASE_URL}/organizations/{ORG_ID}/merchants/{MERCHANT_ID}/orders/{order["id"]}',
            headers=headers
        )
        status_response.raise_for_status()
        print(f'✓ Estado actual: {status_response.json()["status"]}')
 
        print('\n✅ ¡Éxito! Orden de pago creada.')
        print(f'👉 Redirige a tu cliente a: {order["paymentUrl"]}')
 
    except requests.exceptions.HTTPError as error:
        print(f'❌ Error: {error.response.json()}')
    except Exception as error:
        print(f'❌ Error: {str(error)}')
 
if __name__ == '__main__':
    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