Dispersar dinero (Payouts)

¿Qué vas a lograr?

Al terminar esta guía podrás enviar dinero desde tu cuenta OnePay a cuentas bancarias de terceros. OnePay ofrece tres velocidades de transferencia según tus necesidades.

Prerrequisitos

Cuenta de OnePay verificada con llaves API
Saldo disponible en tu cuenta OnePay
Datos bancarios del destinatario

Tipos de dispersión

Tipo	Velocidad	Destinatarios	Descripción
ACH	1-3 días hábiles	Personas naturales y jurídicas	Transferencia estándar bancaria
TURBO	Menos de 2 horas*	Personas naturales y jurídicas	Transferencia rápida
INSTANT	Inmediata	Solo personas naturales con Transfiya	Transferencia instantánea

*El tiempo de las transferencias TURBO puede variar según el banco del destinatario y la hora de la transacción.

Diagrama de flujo

Paso a paso

Crear el cliente destinatario

Registra a la persona o empresa que recibirá el dinero:

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: dest-001" \
  -d '{
    "user_type": "natural",
    "first_name": "Carlos",
    "last_name": "Ramírez",
    "email": "carlos@ejemplo.com",
    "phone": "+573109998877",
    "document_type": "CC",
    "document_number": "1234567890"
  }'

Consultar bancos disponibles

curl https://api.onepay.la/v1/accounts/banks \
  -H "Authorization: Bearer sk_test_xxx"

Esto retorna la lista de bancos con sus IDs. Usa el id del banco correspondiente al crear la cuenta.

Registrar la cuenta bancaria del destinatario

Para dispersiones no necesitas authorization: true. La autorización solo es necesaria si vas a debitar la cuenta (cobrar).

curl https://api.onepay.la/v1/accounts \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cuenta-dest-001" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "bank_id": "BANK_ID",
    "subtype": "SAVINGS",
    "account_number": "123456789"
  }'

Crear la dispersión

curl https://api.onepay.la/v1/cashouts \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: dispersion-001" \
  -d '{
    "amount": 500000,
    "customer_id": "CUSTOMER_ID",
    "account_id": "ACCOUNT_ID",
    "currency": "COP",
    "method": "ACH",
    "description": "Pago proveedor Enero 2025"
  }'

Cambia method según la velocidad que necesites: ACH, TURBO o INSTANT.

Escuchar el webhook de dispersión

Implementa el Webhook de dispersiones para recibir la notificación cuando la transferencia se procese.Estados posibles del cashout:

Verificar tu saldo

Antes de crear una dispersión, verifica que tienes saldo suficiente:

curl https://api.onepay.la/v1/balance \
  -H "Authorization: Bearer sk_test_xxx"

Errores comunes

Error	Causa	Solución
Saldo insuficiente	No tienes fondos para cubrir la dispersión	Recarga tu cuenta o espera a que se acrediten cobros pendientes
`validation_error`	Falta `account_id`, `customer_id` o `method`	Verifica que envías todos los campos requeridos
Cuenta inválida	El número de cuenta no existe en el banco	Verifica los datos bancarios con el destinatario
Banco no disponible	El banco está fuera de servicio temporalmente	Reintenta más tarde o usa otro tipo de transferencia

Inicio rápido

Cobrar (Recaudo)

Pagar (Dispersiones)

Webhooks

IA (MCP)

Verificación

Configuración

Artículos

¿Qué vas a lograr?

Prerrequisitos

Tipos de dispersión

Diagrama de flujo

Paso a paso

Verificar tu saldo

Errores comunes

Siguiente paso

Implementar webhooks

Cobrar con link de pago

​¿Qué vas a lograr?

​Prerrequisitos

​Tipos de dispersión

​Diagrama de flujo

​Paso a paso

​Verificar tu saldo

​Errores comunes

​Siguiente paso

Implementar webhooks

Cobrar con link de pago

¿Qué vas a lograr?

Prerrequisitos

Tipos de dispersión

Diagrama de flujo

Paso a paso

Verificar tu saldo

Errores comunes

Siguiente paso