📘
Versión quedará deprecada a contar del 01 de marzo de 2026. Se recomienda utilizar la API V2

API Payouts - Perú

Esta documentación para desarrolladores proporciona toda la información necesaria para integrar el servicio de Payouts en Perú.

Tabla de Contenidos

Requisitos
Diagrama de integración
Autenticación
Endpoints API Payouts
Manejo de errores
Webhooks
Sandbox Payouts
Ejemplos de llamados

1. Requisitos

Una clave API o Token de Floid habilitada con el servicio de payouts. Para activar esto debes contactarte con el equipo comercial de Floid.
Entorno de Desarrollo: Configura tu entorno de desarrollo con las bibliotecas necesarias para realizar solicitudes HTTPs.
Saldo disponible en tu cuenta para realizar las dispersiones

👍
Recuerda que siempre vas a necesitar el token de Floid para consumir los servicios de Floid.

2. Diagrama de integración

❗️
Si el saldo de tu cuenta no es suficiente para cubrir las dispersiones, la solicitud no se realizará hasta que exista un monto suficiente.

3. Autenticación

La autenticación se realiza mediante un token de API. Este token debe ser incluido en los encabezados de todas las solicitudes.

Encabezados de Autenticación

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

4. Endpoints de la API

Host Producción: https://api.floid.app

Crear un Payout

URL: {{HOST}}/pe/payout/create

Postman Collection 🟠

Método: POST

Descripción: Crea un nuevo payout o dispersión para uno o más beneficiarios en Perú.

Body de la Solicitud:

{
    "currency": 1,
    "amount": 3,
    "beneficiary_account": "00200000123456789012",
    "callbackurl": "https//..." // Opcional
}

Parámetros:

Parámetro	Descripción	Tipo	Requerido	Longitud
`currency`	Código de moneda (1 Soles, 2 Dólares americanos)	Short	Sí	4.0
`amount`	Importe de la transferencia en la moneda indicada. Se validará que no sea cero. Se permiten hasta dos decimales.	Double	Sí	18.2
`beneficiary_account`	Código de cuenta interbancario (CCI) del beneficiario final	String	Sí	20
`callbackurl`	URL del servicio donde se recibirán las notificaciones	String	No	-

La API de payout es una orquestación de servicios que se conecta como interoperador antes nuestros partners. En ese sentido, la respuesta de nuestra api para pagos exitosos se basa en dos casos:

Respuesta a cuentas beneficiarias al Banco De Crédito del Perú
Respuesta a cuentas beneficiarias diferentes al Banco De Crédito del Perú

Respuesta Exitosa a cuentas Banco De Crédito del Perú

{
    "code": 200,
    "msg": "OK",
    "caseid": "ea92asda28-9768-4aec-b3e2-05169a92f5ea",
    "date": "2025-10-12 10:12:18",
    "status": "SUCCESSFUL",
    "data": {
        "BeneficiaryBank": "Banco De Crédito Del Perú",
        "Amount": 21,
        "BeneficiaryAccount": "1231321321321321",
        "DebtorAccount": "3452343243242423",
        "TransferId": "FLOID-9be89asdjw2c"
    },
    "consumerId": "-"
}

Respuesta Exitosa a cuentas NO Banco De Crédito del Perú

{
    "code": 200,
    "msg": "OK",
    "caseid": "c0202468-05d7-4891-9ea4-27b7123jh5d34",
    "date": "2025-10-06 09:08:03",
    "status": "SUCCESSFUL",
    "data": {
        "BeneficiaryDocument": "12313213",
        "BeneficiaryName": "ANDRES ACOSTA POBLETE",
        "BeneficiaryAddress": "",
        "BeneficiaryPhone": 0,
        "BeneficiaryMobile": 0,
        "BeneficiaryBank": "BBVA Continental",
        "Amount": "2",
        "TransferId": "209809808979790372432
        "BankTransferId": 1111111,
        "ResponseDescription": "Response"
    },
    "consumerId": "-"
}

Estados Posibles:

Status	Descripción
`PENDING`	La transferencia está siendo procesada
`SUCCESSFUL`	La transferencia se completó exitosamente
`ERROR`	Hubo un error en la transferencia

Consultar el Estado de un Payout

URL: {{HOST}}/pe/payout/status

Postman Collection 🟠

Método: POST

Descripción: Obtiene el estado de un payout previamente creado.

Body:

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

Parámetros:

Parámetro	Descripción	Tipo	Requerido
`payout_caseid`	Identificador único del payout	String	Sí

Respuesta Exitosa:

{
    "code": 200,
    "msg": "OK",
    "caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9",
    "date": "2024-08-02 12:03:25",
    "status": "SUCCESSFUL",
    "data": {
        "BeneficiaryDocument": "111111111",
        "BeneficiaryName": "MARIA ALBERTINA TAMOS LLACSAHUANGA",
        "BeneficiaryAddress": "",
        "BeneficiaryPhone": 0,
        "BeneficiaryMobile": 0,
        "BeneficiaryBank": "Banco De Crédito Del Perú",
        "Amount": "1",
        "TransferId": "2024080211031600588191101930",
        "BankTransferId": 262301,
        "ResponseDescription": "Contabilización exitosa. Mod: 21 Trn: 2035 Rel: 6."
    }
}

Bancos Disponibles en Perú

BCP (Banco de Crédito del Perú)
Falabella
BANBIF
BBVA
SCOTIABANK
PICHINCHA
INTERBANK
RIPLEY
Banco de la Nación
Mi Banco
Caja Arequipa
Caja Cuzco
Caja Huancayo
Caja Piura
Caja Sullana
Caja Trujillo

5. Manejo de Errores

Estructura de Respuesta de Error

{
    "code": 400,
    "error_type": "string",
    "error_code": "string",
    "error_message": "string",
    "display_message": "string",
    "caseid": "string"
}

Parámetro	Descripción	Tipo
`code`	Código HTTP del error.	Int
`error_type`	Código específico del error definido por Floid.	String
`error_code`	Código específico del error definido por Floid. Se puede usar programáticamente.	String
`error_message`	Mensaje que entrega detalles sobre el error. Puede cambiar con el tiempo por lo que no debe ser usado programáticamente.	String
`display_message`	Mensaje con detalles del error que puede ser mostrado al usuario en tu front-end . Puede cambiar con el tiempo por lo que no debe ser usado programáticamente.	String
`caseid`	Identificador único para cada request que se realiza a la API de Floid. Se generará al inicio de la consulta y será parte del response.	String

Ejemplos

{
  "code": 400,
  "error_type": "PAYOUTS",
  "error_code": "INVALID_PAYOUT_TOKEN",
  "error_message": "Payouts token is not valid.",
  "display_message": "El token de payouts no es válido",
  "caseid":"' . $caseid . '"
}

{
  "code": 400,
  "error_type": "TRANSFER",
  "error_code":  "TRANSFER_ERROR",
  "error_message": "' . $error_message . '",
  "display_message": "' . $display_message . '",
  "caseid":"' . $caseid . '"
}

{
  "code": 400,
  "error_type": "INVALID_CCI",
  "error_code": "INVALID_CCI",
  "error_message": "El CCI ingresado no es válido",
  "display_message": "El CCI ingresado no es válido",
  "caseid":"' . $caseid . '"
}

{
  "code": 400,
  "error_type": "TRANSFER",
  "error_code": "TRANSFER_ERROR",
  "error_message": "There was an error making the transfer. (Tipo de Cuenta a Acreditar Inv\u00e1lido)",
  "display_message": "Ha habido un error realizando la transferencia. (Tipo de Cuenta a Acreditar Inv\u00e1lido)",
  "caseid": "673be354ae265369b630f030"
}

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. ' . $message . '",
  "caseid":"' . $caseid . '"
}

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST_AMOUNT",
  "error_message": "The amount to be transferred must be different from 0.00.",
  "display_message": "Monto a transferir debe ser distinto a 0.00",
  "caseid":"' . $caseid . '"
}

{
  "code": 400,
  "error_type": "SERVICE_ERROR",
  "error_code": "SERVICE_UNAVAILABLE",
  "error_message": "The service is unavailable",
  "display_message": "The service is unavailable.",
  "caseid": "xxxx - xxx - xxxx"
}

{
  "code": 400,
  "error_type": "AUTH_ERROR",
  "error_code": "METHOD_NOT_AUTH",
  "error_message": "This method is not authorized",
  "display_message": "El metodo no está autorizado",
  "caseid": "xxxx - xxx - xxxx"
}

{
  "code": 429,
  "error_type": "TOO_MANY_REQUESTS",
  "error_code": "TOO_MANY_REQUESTS",
  "error_message": "Too many Requests.",
  "display_message": "Ha superado el limite de requests.",
  "caseid": "xxxx - xxx - xxxx"
}

{
  "code": 481,
  "error_type": "ERROR_GENERAL",
  "error_code": "DATA_FAILED",
  "error_message": "Error al intentar obtener los resultados. Por favor reintentar.",
  "display_message": "Error al intentar obtener los resultados. Por favor reintentar.",
  "caseid": "xxxx - xxx - xxxx"
}

Códigos de Error

Errores de Servicio

Parámetro Code	MSJ	Description
`400`	INVALID_PAYOUT_TOKEN	El token de payouts no es válido
`400`	TRANSFER_ERROR	No se pudo realizar la transferencia.
`400`	INVALID_CCI	El CCI ingresado no es válido
`400`	INVALID_REQUEST	La request no es válida. Revisa el body y headers e intenta nuevamente.
`400`	INVALID_REQUEST_AMOUNT	Monto a transferir debe ser distinto a 0.00.

Errores Generales

Parámetro Code	MSJ	Description
`400`	INVALID_REQUEST	La solicitud contiene parámetros inválidos o faltantes.
`400`	INVALID_CREDENTIALS	Credenciales de la cuenta inválidas.
`400`	METHOD_NOT_AUTH	El token de API es inválido o ha expirado para consumir el servicio.
`400`	NOT_FOUND	El recurso solicitado no fue encontrado.
`400`	SERVICE_UNAVAILABLE	El servicio de la API de Floid no está disponible en el momento de la consulta.
`400`	INVALID_PAYOUT_TOKEN	El token de payouts no es válido
`429`	TOO_MANY_REQUESTS	Ha superado el límite de requests por segundo.
`481`	DATA_FAILED	Error al intentar obtener la respuesta a la consulta.
`500`	INTERNAL_ERROR	Ocurrió un error interno en el servidor.

6. Webhooks

Para recibir notificaciones en tiempo real sobre cambios en los estados de los payouts, agrega el parámetro callbackurl al body de tu solicitud.

Ejemplo con Webhook:

{
    "currency": 1,
    "amount": 3,
    "beneficiary_account": "00200000123456789012",
    "callbackurl": "https://tu-webhook.com/endpoint"
}

Verificación de Webhooks:

Para verificar la autenticidad de los webhooks, puedes configurar una secret key. Contacta con nuestro equipo técnico para configurar esto.

7. Sandbox Payouts

Para pruebas, utiliza los siguientes datos de prueba:

CCIS de prueba:
00310001700199141199: success cuentas no bcp
00200000123456789012: success cuentas bcp
22222222222222222222: moneda inválida
33333333333333333333: cuenta bloqueada
44444444444444444444: máx de operaciones diarias
55555555555555555555: sin fondos
Monto de prueba: Cualquier valor entre 1 y 1000
Currency: 1 (Soles)

8. Ejemplos de llamados

Crear Payout

curl -X POST "https://api.floid.app/pe/payout/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": 1,
    "amount": 100.50,
    "beneficiary_account": "00200000123456789012",
    "callbackurl": "https://tu-webhook.com/endpoint"
  }'

Consultar Estado

curl -X POST "https://api.floid.app/pe/payout/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_caseid": "39fbf970-0eda-4a09-aee7-29cb8d41fbd9"
  }'

Payout Perú

📘
Versión quedará deprecada a contar del 01 de marzo de 2026. Se recomienda utilizar la API V2

API Payouts - Perú

Tabla de Contenidos

1. Requisitos

👍
Recuerda que siempre vas a necesitar el token de Floid para consumir los servicios de Floid.

2. Diagrama de integración

❗️
Si el saldo de tu cuenta no es suficiente para cubrir las dispersiones, la solicitud no se realizará hasta que exista un monto suficiente.

3. Autenticación

4. Endpoints de la API

Crear un Payout

Consultar el Estado de un Payout

Bancos Disponibles en Perú

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

6. Webhooks

7. Sandbox Payouts

8. Ejemplos de llamados

Crear Payout

Consultar Estado

📘Versión quedará deprecada a contar del 01 de marzo de 2026. Se recomienda utilizar la API V2

API Payouts - Perú

Tabla de Contenidos

1. Requisitos

👍Recuerda que siempre vas a necesitar el token de Floid para consumir los servicios de Floid.

2. Diagrama de integración

❗️Si el saldo de tu cuenta no es suficiente para cubrir las dispersiones, la solicitud no se realizará hasta que exista un monto suficiente.

3. Autenticación

4. Endpoints de la API

Crear un Payout

Consultar el Estado de un Payout

Bancos Disponibles en Perú

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

6. Webhooks

7. Sandbox Payouts

8. Ejemplos de llamados

Crear Payout

Consultar Estado

📘
Versión quedará deprecada a contar del 01 de marzo de 2026. Se recomienda utilizar la API V2

👍
Recuerda que siempre vas a necesitar el token de Floid para consumir los servicios de Floid.

❗️
Si el saldo de tu cuenta no es suficiente para cubrir las dispersiones, la solicitud no se realizará hasta que exista un monto suficiente.