Crear un Pago

Prerrequisitos

Antes de crear un pago necesitas:

Una cuenta pre-financiada — creada vía POST /api/v2/customers/pre-fund/create
Saldo suficiente — verifica vía GET /api/v2/customers/balances
Datos del beneficiario — cuenta bancaria, dirección de billetera o alias de pago del destinatario

Configurar Cuentas Pre-Financiadas

¿Aún no tienes una cuenta pre-financiada? Comienza aquí.

Flujo Completo de Pago

Verificar Saldo Disponible

Confirma que tienes fondos suficientes antes de enviar el pago.

GET /api/v2/customers/balances

Respuesta

[
  {
    "id": "balance-id",
    "currency": "COP",
    "amount": "10000000.00",
    "accountId": "prefund-account-id"
  }
]

Crear el Pago

Envía la solicitud de pago con tu cuenta pre-financiada, monto y beneficiario.

POST /api/v2/payouts

Seguir el Estado

Consulta el pago o escucha webhooks hasta que alcance un estado terminal (COMPLETED, FAILED, REJECTED, ERROR o REFUNDED).

Ejemplo de Implementación

curl -X POST https://sandbox.killb.app/api/v2/payouts \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pago-2024-001" \
  -d '{
    "preFundAccountId": "prefund-account-id",
    "amount": 500000,
    "externalId": "pago-2024-001",
    "beneficiary": {
      "type": "BANK",
      "account": {
        "firstName": "Maria",
        "lastName": "Garcia",
        "email": "[email protected]",
        "phone": "3001234567",
        "document": { "type": "CC", "number": "12345678" },
        "accountNumber": "123456789",
        "bankCode": "001",
        "type": "savings",
        "countryCode": "CO"
      }
    }
  }'

const crearPago = async (preFundAccountId, amount, beneficiary) => {
  const response = await fetch(
    'https://sandbox.killb.app/api/v2/payouts',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        preFundAccountId,
        amount,
        beneficiary
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Pago fallido: ${JSON.stringify(error)}`);
  }

  return response.json();
};

// Ejemplo: dispersar 500,000 COP vía Bank Transfer
const pago = await crearPago(
  'prefund-account-id',
  500000,
  {
    type: 'BANK',
    account: {
      firstName: 'Maria',
      lastName: 'Garcia',
      email: '[email protected]',
      phone: '3001234567',
      document: { type: 'CC', number: '12345678' },
      accountNumber: '123456789',
      bankCode: '001',
      type: 'savings',
      countryCode: 'CO'
    }
  }
);

console.log('ID del Pago:', pago.id);
console.log('Estado:', pago.status);

import requests

def crear_pago(pre_fund_account_id, amount, beneficiary, access_token):
    response = requests.post(
        'https://sandbox.killb.app/api/v2/payouts',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
            'Idempotency-Key': f'pago-{pre_fund_account_id}-{amount}'
        },
        json={
            'preFundAccountId': pre_fund_account_id,
            'amount': amount,
            'beneficiary': beneficiary
        }
    )
    response.raise_for_status()
    return response.json()

# Ejemplo: dispersar 500,000 COP vía Bank Transfer
pago = crear_pago(
    pre_fund_account_id='prefund-account-id',
    amount=500000,
    beneficiary={
        'type': 'BANK',
        'account': {
            'firstName': 'Maria',
            'lastName': 'Garcia',
            'email': '[email protected]',
            'phone': '3001234567',
            'document': {'type': 'CC', 'number': '12345678'},
            'accountNumber': '123456789',
            'bankCode': '001',
            'type': 'savings',
            'countryCode': 'CO'
        }
    },
    access_token=token
)

print(f"Pago creado: {pago['id']} — {pago['status']}")

Respuesta:

{
  "id": "payout-abc123",
  "amount": 500000,
  "currency": "COP",
  "status": "PENDING",
  "externalId": "pago-2024-001",
  "beneficiary": {
    "type": "BANK",
    "account": { ... }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Tipos de Beneficiario

Bank Transfer (Colombia)
BREB (Colombia)

Transferencia estándar a cuenta bancaria colombiana vía Bank Transfer.

{
  "type": "BANK",
  "account": {
    "firstName": "Maria",
    "lastName": "Garcia",
    "email": "[email protected]",
    "phone": "3001234567",
    "document": {
      "type": "CC",
      "number": "12345678"
    },
    "accountNumber": "123456789",
    "bankCode": "001",
    "type": "savings",
    "countryCode": "CO"
  }
}

Campos requeridos: firstName o companyName, lastName, email, phone, document, accountNumber, bankCode, type, countryCodeUsa GET /api/v2/banks para consultar los valores válidos de bankCode.

Dispersión vía alias registrado (teléfono, email, cédula o alias BREB).

{
  "type": "BREB",
  "account": {
    "firstName": "Carlos",
    "lastName": "Lopez",
    "email": "[email protected]",
    "phone": "3109876543",
    "document": {
      "type": "CC",
      "number": "87654321"
    },
    "aliasType": "PHONE",
    "alias": "3109876543",
    "countryCode": "CO"
  }
}

Tipos de alias: NATIONAL_ID, PHONE, EMAIL, ALPHANUMERIC, BUSINESS_ID

Verificar Saldo Antes del Pago

Siempre verifica el saldo disponible antes de enviar pagos grandes:

const verificarSaldo = async (preFundAccountId, montoRequerido) => {
  const balances = await fetch('/api/v2/customers/balances', {
    headers: { 'Authorization': `Bearer ${token}` }
  }).then(r => r.json());

  const cuenta = balances.find(b => b.accountId === preFundAccountId);

  if (!cuenta || parseFloat(cuenta.amount) < montoRequerido) {
    throw new Error(
      `Saldo insuficiente. Disponible: ${cuenta?.amount ?? 0}, Requerido: ${montoRequerido}`
    );
  }

  return cuenta;
};

Idempotencia

Para evitar dispersiones duplicadas en reintentos de red, envía un header único Idempotency-Key en cada solicitud de creación de pago. Si se recibe la misma clave dos veces, KillB devuelve el pago original en lugar de crear uno nuevo.

Idempotency-Key: <tu-referencia-única-de-pago>

Usa un identificador único y estable como clave — tu ID de pago interno o un UUID vinculado a la transacción funciona bien.

Listar Pagos

Recupera todos los pagos con filtros opcionales:

const listarPagos = async ({ status, externalId, page = 1, limit = 20 } = {}) => {
  const params = new URLSearchParams({ page, limit });
  if (status) params.set('status', status);
  if (externalId) params.set('externalId', externalId);

  const response = await fetch(
    `https://sandbox.killb.app/api/v2/payouts?${params}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );

  return response.json(); // { payouts: [...], totalPage: N }
};

// Obtener todos los pagos pendientes
const pendientes = await listarPagos({ status: 'PENDING' });

Comenzar

Conceptos Principales

Usuarios y KYC

Cuentas

Cuentas Pre-Financiadas

Pagos

On/Off Ramps

Ahorros y Custodia

Webhooks

Recursos

Prerrequisitos

Configurar Cuentas Pre-Financiadas

Flujo Completo de Pago

Ejemplo de Implementación

Tipos de Beneficiario

Verificar Saldo Antes del Pago

Idempotencia

Listar Pagos

Próximos Pasos

Seguimiento de Estado

Configurar Webhooks

​Prerrequisitos

Configurar Cuentas Pre-Financiadas

​Flujo Completo de Pago

​Ejemplo de Implementación

​Tipos de Beneficiario

​Verificar Saldo Antes del Pago

​Idempotencia

​Listar Pagos

​Próximos Pasos

Seguimiento de Estado

Configurar Webhooks

Prerrequisitos

Flujo Completo de Pago

Ejemplo de Implementación

Tipos de Beneficiario

Verificar Saldo Antes del Pago

Idempotencia

Listar Pagos

Próximos Pasos