Payout Perú

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

Parámetros del Request

🏦 Ejemplo BCP

{
  "currency": "PEN",
  "amount": 100.50,
  "beneficiary": {
    "entity": "BCP",
    "account": "0031000170019914119"
  },
  "name": "Andres Poblete",
  "custom": {
    "some": "metadata"
  },
  "callbackurl": "https://tuwebhook.com",
  "sandbox": false
}

🏦 Ejemplo Otros Bancos

{
  "currency": "PEN",
  "amount": 100.50,
  "beneficiary": {
    "entity": "INTERBANK",
    "account": "0031000170019914119"
  },
  "name": "Andres Poblete",
  "callbackurl": "https://tuwebhook.com",
  "sandbox": false
}

📘

Importante destacar que 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 Yape

{
  "currency": "PEN",
  "amount": 100.50,
  "beneficiary": {
    "entity": "YAPE",
    "account": "5197213136",
    "name": "Andres Poblete"
  },
  "custom": {
    "some": "metadata"
  },
  "callbackurl": "https://tuwebhook.com",
  "sandbox": false
}

✅ Respuesta Exitosa (Formato Unificado)

{
  "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."
  }
}

📘

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

🔄 Estados Posibles

Limitaciones de Uso

Para cada transacción realizada existen las siguientes limitaciones:

1. Transferencia a entidades bancarias:
   1. Monto mínimo de transferencia: 1 PEN / 1 USD
   2. Monto máximo de transferencia: 30K PEN / 10K USD
   3. Transferencias máximas
2. Transferencias via YAPE:
   1. Monto mínimo
   2. Monto máximo 30 K PEN/ 10 K USD

Listado entidades

'BCP' = 'Banco de Crédito del Perú',
'INTERBANK' = 'Interbank',
'SCOTIA' = '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',
'CPIURA' = 'CAJA PIURA',
'CAREQUIPA' = 'CAJA AREQUIPA',
'CHUANCAYO' = 'CAJA HUANCAYO',
'CTRUJILLO' = 'CAJA TRUJILLO',
'CSULLANA' = 'CAJA SULLANA',
'CCUZCO' = 'CAJA CUZCO',

Interbank

📊 /pe/payout/status

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

Request

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

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": "BCP-20251022-001",
    "message": "Contabilización exitosa. Mod: 21 Trn: 2035 Rel: 6.",
    "updated_at": "2025-10-23T10:15:22Z"
  }
}

⚠️ Errores Comunes

Ejemplo

{
  "code": 404,
  "error_type": "PAYOUTS",
  "error_code": "NOT_FOUND",
  "error_message": "No se encontró información para el payout_caseid indicado.",
  "display_message": "El identificador no corresponde a una transacción válida.",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9"
}

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

Ejemplo

{
  "event": "payout.update",
  "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
  "status": "SUCCESSFUL",
  "entity": "BCP",
  "data": {
    "amount": 100.50,
    "currency": "PEN",
    "beneficiary_account": "0031000170019914119",
    "updated_at": "2025-10-23T10:25:50Z"
  }
}

🧪 Sandbox

Permite probar integraciones sin afectar cuentas reales, por ejemplo:

{
  "currency": "PEN",
  "amount": 10.00,
  "beneficiary": {
    "entity": "BCP",
    "account": "12345678901234567890"
  },
  "sandbox": true
}

Con el siguiente response:

{
  "code": 200,
  "msg": "OK",
  "status": "SUCCESSFUL",
  "payout_caseid": "SANDBOX-001",
  "data": {
    "entity": "BCP",
    "beneficiary_name": "TEST SANDBOX",
    "amount": 10.00,
    "message": "Transferencia simulada exitosa."
  }
}

🧩 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ú

📞 Soporte

Email: [email protected]

Portal: developers.floid.app

Ambientes disponibles: sandbox, production