Skip to main content

​
Diagrama del Flujo

​
Paso 1: Verificar/Crear Producto por SKU

Endpoint pendiente: Los endpoints de productos (/checkout/product) están en desarrollo. Por ahora, puedes pasar el monto directamente al crear la sesión de checkout (Paso 3). Esta sección se actualizará cuando los endpoints estén disponibles.
Antes de crear un checkout, verifica si el producto existe en Cobrix. Si no existe, créalo.

​
1.1 Buscar Producto

# PENDIENTE - Endpoint en desarrollo
curl -X GET "https://sandbox-api.cobrix.co/api/checkout/company/{companyId}/product/sku/PROD-001" \
  -H "Authorization: Bearer tu_access_token"
Response (200 - Encontrado): 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sku": "PROD-001",
  "name": "Membresía Premium",
  "amountMinor": 5000,
  "currency": "USD",
  "status": "active"
}

​
1.2 Crear o Actualizar Producto

Pendiente: Este endpoint está en desarrollo. Mientras tanto, usa el monto directamente en la sesión de checkout.
El endpoint es idempotente: si el SKU existe, actualiza; si no, crea. 
# PENDIENTE - Endpoint en desarrollo
curl -X POST "https://sandbox-api.cobrix.co/api/checkout/product" \
  -H "Authorization: Bearer tu_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "22991695-c790-4ed2-882b-c60e6190d442",
    "sku": "PROD-001",
    "name": "Membresía Premium",
    "description": "Acceso completo por 1 mes",
    "amountMinor": 5000,
    "currency": "USD",
    "metadata": {
      "category": "membership",
      "duration_days": 30
    }
  }'
Campos del Request:
CampoTipoRequeridoDescripción
companyIdUUID✅ID de tu empresa
skustring✅Identificador único del producto
namestring✅Nombre del producto
descriptionstring❌Descripción
amountMinornumber✅Precio en centavos (5000 = $50.00)
currencystring✅USD, VES, COP, MXN
metadataobject❌Datos adicionales (máx 10 campos)
Guarda el id del producto. Lo necesitarás para crear la sesión de checkout.

​
Paso 2: Resolver Cliente

Busca un cliente por email o créalo si no existe. Es idempotente. 
curl -X POST "https://sandbox-api.cobrix.co/api/checkout/resolve-customer" \
  -H "Authorization: Bearer tu_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "22991695-c790-4ed2-882b-c60e6190d442",
    "email": "[email protected]",
    "name": "Juan Pérez",
    "phone": "+58 412-1234567"
  }'
Response: 
{
  "companyCustomerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "Juan Pérez",
  "isNew": true
}
Guarda el companyCustomerId. Lo necesitarás para crear la sesión de checkout.

​
Paso 3: Crear Sesión de Checkout

Con el productId y companyCustomerId, crea la sesión: 
curl -X POST "https://sandbox-api.cobrix.co/api/checkout/session" \
  -H "Authorization: Bearer tu_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "22991695-c790-4ed2-882b-c60e6190d442",
    "companyCustomerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "quantity": 1,
    "successUrl": "https://tu-ecommerce.com/pago-exitoso",
    "cancelUrl": "https://tu-ecommerce.com/pago-cancelado",
    "metadata": {
      "orderId": "ORD-12345"
    }
  }'
Response: 
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "checkoutUrl": "https://sandbox.cobrix.co/checkout/{token}",
  "expiresAt": "2026-01-22T11:00:00.000Z",
  "status": "active",
  "amountMinor": 5000,
  "currency": "USD",
  "allowedMethods": ["pagoMovil", "zelle", "debitoInmediato"]
}

​
Paso 4: Redirigir al Usuario

Envía al usuario a la URL del checkout: 
// Opción 1: Redirección directa
window.location.href = session.checkoutUrl;

// Opción 2: Nueva pestaña
window.open(session.checkoutUrl, '_blank');

​
Experiencia del Usuario

1

Resumen

Usuario ve el monto y detalles del producto
2

Método de Pago

Selecciona cómo quiere pagar
3

Datos

Completa el formulario según el método
4

Confirmación

Recibe confirmación y es redirigido a successUrl

​
Paso 5: Recibir Webhook

Cuando el pago se completa, recibirás un webhook: 
{
  "id": "evt_1234567890abcdef",
  "event": "payment.succeeded",
  "created_at": "2026-01-22T15:30:00.000Z",
  "data": {
    "payment": {
      "transactionId": "txn_abc123",
      "status": "succeeded",
      "amountMinor": 5000,
      "currency": "USD"
    },
    "metadata": {
      "orderId": "ORD-12345"
    }
  }
}
Siempre verifica la firma del webhook antes de procesar. Ver Webhooks.

​
Código Completo

async function processOrder(order) {
  // Paso 1: Producto (PENDIENTE - endpoint en desarrollo)
  // Por ahora, pasar el monto directamente en la sesión
  // const { data: product } = await client.post('/checkout/product', {
  //   companyId: COMPANY_ID,
  //   sku: order.productSku,
  //   name: order.productName,
  //   amountMinor: order.priceInCents,
  //   currency: 'USD'
  // });

  // Paso 2: Cliente
  const { data: customer } = await client.post('/checkout/resolve-customer', {
    companyId: COMPANY_ID,
    email: order.customerEmail,
    name: order.customerName,
    phone: order.customerPhone
  });

  // Paso 3: Checkout Session
  const { data: session } = await client.post('/checkout/session', {
    companyId: COMPANY_ID,
    companyCustomerId: customer.companyCustomerId,
    // productId: product.id, // Usar cuando endpoint de productos esté disponible
    amountMinor: order.priceInCents, // Pasar monto directamente por ahora
    currency: 'USD',
    successUrl: `https://tu-sitio.com/success?order=${order.id}`,
    cancelUrl: `https://tu-sitio.com/cancel?order=${order.id}`,
    metadata: { orderId: order.id }
  });

  // Paso 4: Retornar URL
  return session.checkoutUrl;
}