API Payouts - Chile

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

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}}/cl/payout/create

Postman Collection 🟠

Método: POST

Descripción: Crea un nuevo payout o dispersión para beneficiarios en Chile.

Body de la Solicitud:

{
    "beneficiary_id": "12345678-9",
    "beneficiary_name": "Juan Pérez",
    "beneficiary_account": "1234567890",
    "amount": "1000",
    "beneficiary_account_type": "1",
    "beneficiary_bank_code": "37",
    "beneficiary_email": "[email protected]",
    "description": "Pago de servicios"
}

Parámetros:

Parámetro	Descripción	Tipo	Requerido	Validaciones
`beneficiary_id`	RUT del beneficiario final	String	Sí	Debe ser un RUT válido
`beneficiary_name`	Nombre del beneficiario final	String	Sí	Máximo 40 caracteres
`beneficiary_account`	Número de cuenta del beneficiario	String	Sí	Máximo 10 caracteres
`amount`	Monto de la transferencia (sin decimales)	String	Sí	Máximo 5,000,000
`beneficiary_account_type`	Tipo de cuenta de destino	String	Sí	Debe ser "1", "2" o "3"
`beneficiary_bank_code`	Código del banco de destino	String	Sí	Debe ser un código válido
`beneficiary_email`	Email del beneficiario	String	No	Debe ser email válido si se proporciona
`description`	Mensaje para el beneficiario	String	No	Máximo 100 caracteres si se proporciona

Tipos de Cuenta (beneficiary_account_type):

Código	Tipo
`1`	Cuenta Corriente
`2`	Cuenta Vista
`3`	Cuenta de Ahorro

Respuesta Exitosa:

{
    "code": 200,
    "msg": "OK",
    "caseid": "120564ad-6c0f-4276-ac76-16ffbe6bc5de",
    "date": "2025-08-19 16:25:50",
    "status": "SUCCESSFUL",
    "data": {
        "beneficiary_document": "12345678-9",
        "beneficiary_account": "1234567890",
        "beneficiary_name": "Juan Pérez",
        "amount": "1000",
        "beneficiary_bank": "Banco Santander",
        "reference": "Pago de servicios"
    }
}

Estados Posibles:

Status	Descripción
`PENDING`	La transferencia está siendo procesada
`SUCCESSFUL`	La transferencia se completó exitosamente
`ERROR`	Hubo un error en la transferencia
`INVALID`	Los datos proporcionados no son válidos

Bancos Disponibles en Chile

Código	Banco
`1`	Banco De Chile - Edwards
`9`	Banco Internacional
`12`	Banco Del Estado De Chile
`14`	Scotiabank
`16`	BCI (Bco de Credito e Inv)
`17`	Banco Do Brasil S.a.
`27`	Itau-corpbanca
`28`	Banco Bice
`31`	Hsbc Bank
`37`	Banco Santander
`39`	Itau Chile
`49`	Banco Security
`51`	Banco Falabella
`53`	Banco Ripley
`55`	Banco Consorcio
`57`	Banco Paris
`504`	Bbva (Bco Bilbao Vizcaya Arg)
`672`	Coopeuch
`729`	Prepago Los Heroes
`730`	Tenpo Prepago S.a.
`732`	Tapp Caja Los Andes
`875`	Mercado Pago

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": "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"
}

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:

{
    "beneficiary_id": "12345678-9",
    "beneficiary_name": "Juan Pérez",
    "beneficiary_account": "1234567890",
    "amount": "1000",
    "beneficiary_account_type": "1",
    "beneficiary_bank_code": "37",
    "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:

Transferencia Exitosa:

{
    "beneficiary_id": "111111111",
    "beneficiary_name": "Usuario Prueba",
    "beneficiary_account": "123456789",
    "amount": "1000",
    "beneficiary_account_type": "1",
    "beneficiary_bank_code": "28"
}

Respuesta Exitosa:

{
    "code": 200,
    "msg": "OK",
    "caseid": "120564ad-6c0f-4276-ac76-16ffbe6bc5de",
    "date": "2025-08-19 16:25:50",
    "status": "SUCCESSFUL",
    "data": {
        "beneficiary_document": "111111111",
        "beneficiary_account": "1234567890",
        "beneficiary_name": "Usuario Prueba",
        "amount": "1000",
        "beneficiary_bank": "Banco Santander",
        "reference": "Pago de servicios"
    }
}

Transferencia con Error:

{
    "beneficiary_id": "222222222",
    "beneficiary_name": "Usuario Prueba",
    "beneficiary_account": "987654321",
    "amount": "1000",
    "beneficiary_account_type": "1",
    "beneficiary_bank_code": "28"
}

Error en transferencia:

{
    "code": 200,
    "msg": "OK",
    "caseid": "120564ad-6c0f-4276-ac76-16ffbe6bc5de",
    "date": "2025-08-19 16:25:50",
    "status": "ERROR",
    "data": {
        "beneficiary_document": "111111111",
        "beneficiary_account": "1234567890",
        "beneficiary_name": "Usuario Prueba",
        "beneficiary_bank": "Banco Santander",
        "error_message": "Error al crear la transferencia"
    }
}

Error por fondos insuficientes desde la cuenta origen

{
  "code": 400,
  "msg": "OK",
  "caseid": "8aeea2fb-5923-424b-b8f3-24asd2cab10ba2",
  "date": "2025-11-10 17:07:25",
  "status": "ERROR",
  "data": {
    "ErrorMsg": "Insufficient funds to complete the operation"
  },
  "consumerId": "-"
}

8. Ejemplos de llamados

Crear Payout

curl -X POST "https://api.floid.app/cl/payout/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_id": "12345678-9",
    "beneficiary_name": "Juan Pérez",
    "beneficiary_account": "1234567890",
    "amount": "1000",
    "beneficiary_account_type": "1",
    "beneficiary_bank_code": "37",
    "beneficiary_email": "[email protected]",
    "description": "Pago de servicios"
  }'

Validaciones Importantes

RUT: Debe tener formato válido chileno
Nombre: No puede exceder 40 caracteres
Cuenta: No puede exceder 10 caracteres
Monto: No puede exceder 5,000,000
Tipo de cuenta: Solo acepta valores "1", "2" o "3"
Código de banco: Debe existir en la lista de bancos disponibles
Email: Debe ser una dirección de email válida (opcional)
Descripción: No puede exceder 100 caracteres (opcional)

9. Consultar payout

Para consultar estado de un payout se utiliza. el endpoint

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

Ejemplo de uso

{
    "payout_caseid": "674d24a2-3217-46e8-883f-2a2342af700ae"
}

Con la respuesta

{
    "code": 200,
    "msg": "OK",
    "caseid": "674d24a2-3217-46e8-883f-2a2342af700ae",
    "date": "2025-12-18 15:20:34.22",
    "status": "SUCCESSFUL",
    "data": {
        "beneficiary_document": "111111111",
        "beneficiary_account": "1111111111",
        "beneficiary_name": "ANDRES JOSE ACOSTA POBLET",
        "amount": "400",
        "beneficiary_bank": "Banco Santander",
        "reference": "Transfer"
    }
}

10 Refund

El método Refund permite a los clientes solicitar la devolución de uno o múltiples pagos previamente procesados a través del servicio de Payout Chile.

Mediante este endpoint, el cliente puede enviar una lista de payment_token asociados a pagos previamente generados desde el servicio de Payin. Floid procesará estos tokens y, cuando corresponda, gestionará el reembolso del monto al usuario final que realizó el pago.

De esta forma, Floid actúa como facilitador del proceso de devolución, asegurando que los fondos sean retornados al pagador original del cliente.

Endpoint

{{HOST}}cl/payout/refund

Request

El cliente debe enviar uno o varios payment_token correspondientes a los pagos que desea reembolsar.

Ejemplo Request para 1 payment_token:

{  
  "payment_token": "uighasdsa-21213-asd1233"
}

Ejemplo para múltiples payment_token:

{  
  "payment_token": ["uighasdsa-21213-asd1233", "uighasdsa-21213-asd1233"]  
}

Parámetros

Campo	Tipo	Descripción
payment_token	array[string]	Lista de identificadores únicos de pagos que se desean reembolsar

Lógica de Procesamiento

Al recibir la solicitud, el sistema realiza las siguientes validaciones y acciones:

Validación de existencia
1. Se valida que cada payment_token exista en el sistema.
Validación de elegibilidad
1. El pago debe encontrarse en un estado que permita reembolso.
2. No debe existir un reembolso previamente solicitado o procesado.
Procesamiento del request
1. El sistema registra los tokens aceptados y rechazados.
2. Se genera un identificador único de caso (caseid) para trazabilidad.

Response

Si la solicitud es aceptada, el sistema devuelve un identificador del caso asociado al proceso de reembolso.

{  
  "code": 200,  
  "msg": "OK",  
  "caseid": "21b7371c-8c5a-463b-9c42-28e88d1a7fe3"  
}

Campos de respuesta

Campo	Tipo	Descripción
code	integer	Código de respuesta del servicio
msg	string	Mensaje de estado
caseid	string	Identificador único del proceso de refund

Payout Chile

API Payouts - Chile

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

Bancos Disponibles en Chile

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

6. Webhooks

7. Sandbox Payouts

8. Ejemplos de llamados

Crear Payout

Validaciones Importantes

9. Consultar payout

10 Refund

Endpoint

Parámetros

Lógica de Procesamiento

Response

API Payouts - Chile

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

Bancos Disponibles en Chile

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

6. Webhooks

7. Sandbox Payouts

8. Ejemplos de llamados

Crear Payout

Validaciones Importantes

9. Consultar payout

10 Refund

Endpoint

Parámetros

Lógica de Procesamiento

Response

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