API de Payouts Perú v2 - Floid

La API de Payouts Perú v2 de Floid permite realizar dispersión de fondos unificada hacia bancos y billeteras en el país. Esta versión fue diseñada para consolidar distintos métodos de transferencia (bancarias y billeteras) bajo un solo flujo de integración, reduciendo la complejidad técnica y mejorando la trazabilidad de las operaciones.

Introducción

Con esta nueva versión, las empresas pueden realizar pagos masivos, devoluciones o dispersiones individuales sin manejar múltiples endpoints por banco o canal.

La API soporta operaciones hacia:

• 🏦 Bancos via conexión interoperabilidad
• 📱 Yape (B2C Wallet)

Cada operación cuenta con un identificador único (payout_caseid) para su seguimiento en tiempo real mediante el endpoint /status o vía webhook.

Esta nueva versión propone la creación de una API de Payout Unificada, que concentre los distintos métodos de dispersión en un solo flujo.
El cliente solo debe invocar dos endpoints: uno para crear (/create) y otro para consultar (/status).

Beneficios:

• ✅ Una única integración
• 🧩 Mismo modelo de request y response
• ⚙️ Extensible a nuevas entidades (Plin, etc.)
• 🔍 Simplificación del mantenimiento
• 📊 Mayor trazabilidad mediante payout_caseid

Arquitectura General

⚙️ /pe/payout/create

Descripción

Crea un payout hacia una entidad financiera o billetera.
El campo entity determina el canal de destino (ej. BCP, INTERBANK, YAPE).

URL:

POST https://api.floid.app/pe/payout/create_v2

Headers

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Parámetros del Request

🏦 Ejemplo: Payout a BCP

Request:

{
  "currency": "PEN",
  "amount": 100.50,
  "beneficiary": {
    "entity": "BCP",
    "account": "00210011700199141190"
  },
  "name": "Andres Poblete",
  "custom": {
    "order_id": "ORD-12345"
  },
  "callbackurl": "https://tuwebhook.com/payouts",
  "sandbox": false
}

Response:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "data": {
    "entity": "BCP",
    "beneficiary_name": "Andres Poblete",
    "amount": 100.50,
    "transaction_id": "FLOID-3477bea5677a",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

📘

Importante: El método permite verificar la cuenta del beneficiario previo a la dispersión, para así garantizar que cada transacción se realiza a cuentas verificadas.

🏦 Ejemplo: Payout a Otros Bancos (Interoperabilidad)

Request:

{
  "currency": "PEN",
  "amount": 250.00,
  "beneficiary": {
    "entity": "INTERBANK",
    "account": "00300011234567890123"
  },
  "name": "Maria Lopez",
  "callbackurl": "https://tuwebhook.com/payouts",
  "sandbox": false
}

Response:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "7e1a8907-c27a-4331-a8da-2763c3c2031c",
  "data": {
    "entity": "INTERBANK",
    "beneficiary_name": "Maria Lopez",
    "amount": 250.00,
    "transaction_id": "ALFIN-20251121-456",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T11:15:30-05:00"
  }
}

📱 Ejemplo: Payout via Yape

Request:

{
  "currency": "PEN",
  "amount": 50.00,
  "beneficiary": {
    "entity": "YAPE",
    "account": "987654321"
  },
  "name": "Carlos Rodriguez",
  "custom": {
    "payment_type": "refund"
  },
  "callbackurl": "https://tuwebhook.com/payouts",
  "sandbox": false
}

Response:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "2780c9f5-6af7-4597-83a5-2491835da1b4",
  "data": {
    "entity": "YAPE",
    "beneficiary_name": "Carlos Rodriguez",
    "amount": 50.00,
    "transaction_id": "cmi90ltcp0i3p9mi1gsgthxuv",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

📘

Nota: Los campos sender_company_name, sender_type, sender_category, beneficiary_id, beneficiary_type, description y reference se configuran automáticamente para Yape.

✅ Respuesta Exitosa (Formato Unificado)

Todas las respuestas exitosas siguen el mismo formato:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "data": {
    "entity": "BCP",
    "beneficiary_name": "Andres Poblete",
    "amount": 100.50,
    "transaction_id": "BCP-20251022-001",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

💡

El campo payout_caseid es el identificador único del payout y se utiliza para consultas posteriores en /status.

🔄 Estados Posibles

⚠️ Errores Comunes

Ejemplo de Error:

{
  "code": 400,
  "msg": "INVALID_REQUEST",
  "status": "ERROR",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "data": {
    "error_message": "Campos requeridos faltantes o vacíos: amount"
  }
}

📋 Limitaciones de Uso

Para cada transacción realizada existen las siguientes limitaciones:

1. Transferencias a entidades bancarias:

• Monto mínimo de transferencia: 1 PEN / 1 USD
• Monto máximo de transferencia: 30,000 PEN / 10,000 USD

2. Transferencias via YAPE:

• Monto mínimo: 1 PEN
• Monto máximo: 3,500 PEN (límite B2C)

🏦 Listado de Entidades Soportadas

'BCP'        = 'Banco de Crédito del Perú'
'INTERBANK'  = 'Interbank'
'SCOTIABANK' = 'Scotiabank Perú S.A.A.'
'BBVA'       = 'BBVA Continental'
'NACION'     = 'Banco de la Nación'
'PICHINCHA'  = 'Banco Pichincha'
'FALABELLA'  = 'Banco Falabella Perú S.A.'
'ALFIN'      = 'Banco Azteca Del Perú S.A. - Alfin'
'BANBIF'     = 'BANBIF - Banco Interamericano de Finanzas'
'MIBANCO'    = 'MI BANCO'
'YAPE'       = 'Yape (Billetera Digital)'

Cajas Municipales:

'CPIURA'     = 'Caja Piura'
'CAREQUIPA'  = 'Caja Arequipa'
'CHUANCAYO'  = 'Caja Huancayo'
'CTRUJILLO'  = 'Caja Trujillo'
'CSULLANA'   = 'Caja Sullana'
'CCUZCO'     = 'Caja Cuzco'

📘

Nota: Puedes usar cualquier nombre de banco en el campo entity. Si NO es BCP ni YAPE, automáticamente irá por interoperabilidad via Alfin.

📊 /pe/payout/status

Descripción

Método que permite consultar el estado actual de un payout mediante su identificador payout_caseid.

URL:

POST https://api.floid.app/pe/payout/status_v2

Headers

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Parámetros del Request

Request:

{
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9"
}

✅ Respuesta Exitosa

Ejemplo BCP:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "data": {
    "entity": "BCP",
    "beneficiary_name": "Andres Poblete",
    "amount": 100.50,
    "transaction_id": "FLOID-3477bea5677a",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

Ejemplo Yape:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "2780c9f5-6af7-4597-83a5-2491835da1b4",
  "data": {
    "entity": "YAPE",
    "beneficiary_name": "Carlos Rodriguez",
    "amount": 50.00,
    "transaction_id": "cmi90ltcp0i3p9mi1gsgthxuv",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

⚠️ Errores Comunes

Ejemplo de Error (404):

{
  "code": 404,
  "msg": "NOT_FOUND",
  "status": "ERROR",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "data": {
    "error_message": "El payout no existe."
  }
}

🔔 Webhooks

Descripción

Cuando el cliente incluye un callbackurl en el request, Floid envía notificaciones automáticas cada vez que cambia el estado de la transacción.

Payload del Webhook

{
  "event": "payout.update",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "status": "SUCCESSFUL",
  "entity": "BCP",
  "data": {
    "amount": 100.50,
    "currency": "PEN",
    "beneficiary_name": "Andres Poblete",
    "beneficiary_account": "00210011700199141190",
    "transaction_id": "FLOID-3477bea5677a",
    "message": "Transferencia exitosa",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

Eventos Soportados

📘

Nota: Tu endpoint debe responder con un código HTTP 200 para confirmar la recepción del webhook.

🧪 Sandbox

Permite probar integraciones sin afectar cuentas reales.

Ejemplo de Request en Sandbox

{
  "currency": "PEN",
  "amount": 10.00,
  "beneficiary": {
    "entity": "BCP",
    "account": "00210011700199141190"
  },
  "name": "Test User",
  "sandbox": true
}

Response en Sandbox

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "SANDBOX-BCP-a1b2c3d4",
  "data": {
    "entity": "BCP",
    "beneficiary_name": "Test User",
    "amount": 10.00,
    "transaction_id": "SANDBOX-BCP-a1b2c3d4",
    "message": "Transferencia exitosa (SANDBOX MODE)",
    "updated_at": "2025-11-21T10:30:02-05:00"
  }
}

⚠️

Importante: Las transacciones en modo sandbox NO se ejecutan realmente y NO afectan cuentas bancarias.

🧩 Validación de Cuenta (Servicio Complementario)

El flujo de payout puede complementarse con la validación previa de la cuenta bancaria del beneficiario.
Este servicio puede utilizarse de forma independiente o integrado al proceso de /create.

📘 Documentación completa:
👉 Validación de Cuentas Bancarias Perú

🔐 Autenticación

Todas las peticiones requieren un token de autenticación Bearer en el header:

Authorization: Bearer YOUR_TOKEN

Para obtener tu token de acceso, contacta con el equipo de Floid.

📞 Soporte

Email: [email protected]
Portal: developers.floid.app
Documentación: readme.floid.io

📄 Changelog

v2.0.0 (2025-11-21)

• ✨ Lanzamiento de API v2 unificada
• 🏦 Soporte para múltiples bancos via interoperabilidad
• 📱 Integración con Yape B2C
• 🔄 Formato de respuesta unificado
• 📊 Endpoint /status para consulta de estado
• 🔔 Soporte para webhooks
• 🧪 Modo sandbox para testing

📚 Recursos Adicionales

• Guía de Integración Rápida
• Validación de Cuentas
• Webhooks
• Códigos de Error

© 2025 Floid. Todos los derechos reservados.