Pagar Proveedores (PAYOUT)

Aprende cómo enviar pagos desde tu saldo virtual a cuentas bancarias externas.

¿Qué es PAYOUT?

PAYOUT es el tipo de orden utilizado para enviar fondos desde tu cuenta de saldo virtual a cuentas bancarias externas (proveedores, vendedores, contratistas, etc.).

Casos de Uso

Cómo Funciona

Flujo de Alto Nivel

1. 1

   Verifica tu saldo virtual

   Asegúrate de tener fondos suficientes

2. 2

   Crea contacto de proveedor

   Almacena información del proveedor y cuenta bancaria

3. 3

   Crea orden PAYOUT

   Especifica monto y cuenta bancaria de destino

4. 4

   Fondos son debitados

   Dinero es inmediatamente reservado de tu cuenta virtual

5. 5

   Transferencia bancaria iniciada

   Koywe inicia transferencia al banco del proveedor

6. 6

   Proveedor recibe fondos

   Tiempo de liquidación varía por país y banco de destino (instantáneo hasta el siguiente día hábil)

7. 7

   Recibes confirmación

   Notificación webhook cuando la transferencia se completa

Diagrama de Flujo Detallado

Prerequisitos

Antes de hacer payouts:

Países Soportados

El lado payout de cada corredor. Para la cobertura de payin, las monedas y el rail local detrás de cada uno, ver Corredores y Monedas Soportadas.

Colombia 🇨🇴

• Método: ACH Colombia, Bre-B
• Moneda: COP
• Liquidación: ACH opera por ciclos; Bre-B se liquida en segundos
• Bancos: Todos los bancos colombianos
• Destinos Bre-B: declara rail: "BREB" en la cuenta de destino y pon la llave en accountNumber — ver Rieles de Pago

Brasil 🇧🇷

• Método: Transferencia PIX
• Moneda: BRL
• Liquidación: Instantánea
• Bancos: Todos los bancos brasileños con PIX

México 🇲🇽

• Método: Transferencia SPEI
• Moneda: MXN
• Liquidación: Instantánea ⚡, 24/7
• Límites: Sin límite
• Bancos: Todos los bancos mexicanos

Chile 🇨🇱

• Método: Archivo de pagos masivos
• Moneda: CLP
• Liquidación: 24/7, en un máximo de 5 minutos
• Límites: Sin límite por operación. Los montos grandes se pagan en lotes (batches) de transferencias de CLP 7.000.000 cada una
• Bancos: Todos los bancos chilenos

Argentina 🇦🇷

• Método: Transferencia a un CVU nominativo
• Moneda: ARS
• Liquidación: Instantánea ⚡, 24/7 incluyendo fines de semana y feriados. Sin horario de corte (cut-off)
• Límites: Mínimo ARS 1, sin máximo por operación
• Bancos: Todos los bancos argentinos. Solo cuentas nominativas — la identidad del beneficiario debe coincidir

Perú 🇵🇪

• Método: Transferencia bancaria
• Moneda: PEN, USD
• Bancos: Todos los bancos peruanos
• Límites: Mínimo PEN 1. Máximo PEN 420.000 / USD 75.000 por transferencia hacia Interbank y otros bancos. Sin máximo hacia BCP (en USD, de BCP a BCP)
• Liquidación: Los mismos tiempos rigen para PEN y USD, y dependen del banco de destino:

Otros bancos — el momento de acreditación depende del horario de envío (hora Perú):

Bolivia 🇧🇴

• Método: Transferencia bancaria
• Moneda: BOB
• Liquidación: Hasta 20 minutos, 24/7, salvo la ventana de corte del sistema ACH entre las 23:50 y las 00:10. Lo que entra en ese horario se procesa apenas se restablece el sistema
• Límites: Mínimo equivalente a USD 1, sin máximo por operación
• Revisión de compliance: Hasta USD 1.000 el pago sale automático. Por encima, pasa por una revisión de compliance antes de ejecutarse
• Bancos: Todos los bancos bolivianos

Venezuela 🇻🇪

• Método: Transferencia bancaria
• Moneda: VES
• Liquidación: 1-2 días hábiles
• Bancos: Todos los bancos venezolanos
• Límite diario de pago: $3,500 USD equivalente por día

Estados Unidos 🇺🇸

• Método: Wire o ACH a una cuenta nominativa
• Moneda: USD
• Liquidación: 1-2 días hábiles
• Bancos: Todos los bancos de EE.UU. (requiere routing number)
• Nota: Requiere un onboarding KYB/KYC aparte

Ejemplo Rápido

Aquí hay un flujo PAYOUT simple:

// 1. Verificar saldo
const balance = await getBalance(token, orgId, merchantId, 'COP');
console.log('Disponible:', balance.availableBalance); // ej., 1,000,000 COP
 
// 2. Crear contacto de proveedor
const provider = await createContact(token, orgId, merchantId, {
  firstName: 'Servicios ABC SAS',
  countrySymbol: 'CO',
  documentType: 'NIT',
  documentNumber: '9001234561',
  businessType: 'COMPANY',
  type: 'BUSINESS',
  email: 'proveedor@ejemplo.com'
});
 
// 3. Agregar cuenta bancaria
const bankAccount = await addBankAccount(token, orgId, merchantId, provider.id, {
  name: 'Bancolombia COP',
  kind: 'BANK',
  isDefault: true,
  countrySymbol: 'CO',
  currencySymbol: 'COP',
  entity: 'BANCOLOMBIA',
  accountNumber: '1234567890',
  type: 'CHECKING'
});
 
// 4. Crear orden PAYOUT
const payout = await createPayoutOrder(token, orgId, merchantId, {
  type: 'PAYOUT',
  originCurrencySymbol: 'COP',
  destinationCurrencySymbol: 'COP',
  amountIn: 500000,  // 500,000 COP
  contactId: provider.id,
  destinationAccountId: bankAccount.id,
  description: 'Pago por Factura #INV-001'
});
 
console.log('Payout creado:', payout.id);
console.log('Estado:', payout.status); // "PROCESSING"

Diferencias Clave vs PAYIN

Comparación de Flujo de Pago

PAYIN (Recibir)

Cliente paga → Fondos acreditados → Webhook → Cumplir orden

PAYOUT (Enviar)

Verificar saldo → Crear orden → Fondos debitados → Transferencia bancaria → Confirmación webhook

Requisitos de Saldo

Verificar Saldo Antes de PAYOUT

async function safeCreatePayout(token, orgId, merchantId, payoutData) {
  // 1. Obtener saldo actual
  const balances = await getMerchantBalances(token, orgId, merchantId);
  const balance = balances.find(b => b.currencySymbol === payoutData.currency);
  
  // 2. Verificar saldo disponible
  if (!balance || balance.availableBalance < payoutData.amount) {
    throw new Error(
      `Saldo insuficiente. Disponible: ${balance?.availableBalance || 0} ${payoutData.currency}, ` +
      `Requerido: ${payoutData.amount} ${payoutData.currency}`
    );
  }
  
  console.log(`✓ Saldo suficiente: ${balance.availableBalance} ${payoutData.currency}`);
  
  // 3. Crear payout
  const payout = await createPayoutOrder(token, orgId, merchantId, payoutData);
  
  return payout;
}

Tiempos de Liquidación

Comprender cuándo los proveedores reciben fondos:

Para todos los corredores de payout, incluidos Venezuela, Estados Unidos y la liquidación transfronteriza, ver Corredores y Monedas Soportadas.

Próximos Pasos

Recursos Adicionales

• Conceptos Clave - Órdenes
• Contactos y Cuentas Bancarias
• Manejo de Errores
• Referencia API