Skip to main content

​
¿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

TipoVelocidadDestinatariosDescripción
ACH1-3 días hábilesPersonas naturales y jurídicasTransferencia estándar bancaria
TURBOMenos de 2 horas*Personas naturales y jurídicasTransferencia rápida
INSTANTInmediataSolo personas naturales con TransfiyaTransferencia 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

1

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": "[email protected]",
    "phone": "+573109998877",
    "document_type": "CC",
    "document_number": "1234567890"
  }'
2

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.
3

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

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.
5

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

ErrorCausaSolución
Saldo insuficienteNo tienes fondos para cubrir la dispersiónRecarga tu cuenta o espera a que se acrediten cobros pendientes
validation_errorFalta account_id, customer_id o methodVerifica que envías todos los campos requeridos
Cuenta inválidaEl número de cuenta no existe en el bancoVerifica los datos bancarios con el destinatario
Banco no disponibleEl banco está fuera de servicio temporalmenteReintenta más tarde o usa otro tipo de transferencia

​
Siguiente paso

Implementar webhooks

Recibe notificaciones en tiempo real sobre tus dispersiones.

Cobrar con link de pago

Recauda los fondos que luego dispersarás.