---
updatedAt: 2026-09-16T10:59:48.000Z
agentTools:
  projectIndex: https://readme.floid.io/llms.txt
---

# Validación de cuentas bancarias Perú

Este servicio permite realizar la verificación de la titularidad de un código de cuenta interbancario CCI. Adicionalmente permite validar con el nombre, banco y/o dni la titularidad de la cuenta.

## **Perú**

**URL Perú: {{HOST}}/pe/payout/check\_v2**

[Postman Collection 🟠](https://documenter.getpostman.com/view/18627449/2sA3dyhqUS#27861325-d167-466b-b559-47f3a1cdc1c9)

**Método: POST**

**Descripción:** Este método se utiliza para realizar la verificación de una cuenta. Este payload es para validar cuentas de **bancos distintos a BCP**

**Body de la Solicitud (cuentas no BCP):**

```json Perú
{    
   "currency": 1,
  "beneficiary_account": "0031000170019914123",
  "beneficiary_account_number" :"19193593257041", //Opcional
  //"beneficiary_id": "{{id}}", Opcional
  //"beneficiary_name":" {{name}}", Opcional
  //"beneficiary_bank": {{name}}, Opcional
  //"beneficiary_doc_type":{{int}} , Opcional
  //"custom": "{{string}}", Opcional
}
```

**Parámetros de Ruta:**

[block:parameters]
{
  "data": {
    "h-0": "Parámetro",
    "h-1": "Descripción",
    "h-2": "Tipo",
    "h-3": "In/Out",
    "h-4": "Longitud",
    "0-0": "`currency`",
    "0-1": "Es el código de moneda (1 Soles, 2 Dólares  \namericanos). ",
    "0-2": "Short ",
    "0-3": "In ",
    "0-4": "4.0",
    "1-0": "`beneficiary_account`",
    "1-1": "Es el código de cuenta interbancario (CCI) del beneficiario final. Este Código de Cuenta Interbancario, tiene 20 dígitos, compuesto así: Código de la Entidad Financiera: 3 dígitos. Código de la oficina: 3 dígitos. Número de la cuenta: 12 dígitos.",
    "1-2": "String",
    "1-3": "In",
    "1-4": "20",
    "2-0": "`beneficiary_id`",
    "2-1": "Opcional. DNI del titular de la cuenta.",
    "2-2": "String",
    "2-3": "In",
    "2-4": "15",
    "3-0": "`beneficiary_name`",
    "3-1": "Opcional. Nombre del titular de la cuenta.",
    "3-2": "String",
    "3-3": "In",
    "3-4": "30",
    "4-0": "`beneficiary_bank`",
    "4-1": "Opcional. Nombre del banco de la cuenta que se requiere verificar. ",
    "4-2": "String",
    "4-3": "In",
    "4-4": "20",
    "5-0": "`beneficiary_doc_type`",
    "5-1": "Opcional. Tipo de documento del titular de la cuenta.  \nLos tipos de doc aceptados para validación son:  \n  \n1 DNI  \n2 Carnet de extranjería  \n9 RUC",
    "5-2": "Int",
    "5-3": "In",
    "5-4": "2",
    "6-0": "`custom`(opcional)",
    "6-1": "Información/detalle adicional sobre la transacción. Se muestra en el dashboard",
    "6-2": "String",
    "6-3": "In",
    "6-4": "50"
  },
  "cols": 5,
  "rows": 7,
  "align": [
    "left",
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

> ✅ Tienes dos formas de realizar la solicitud para este servicio de validación:
>
> 1️⃣ Usando solo los parámetros obligatorios: La respuesta incluirá los datos de titularidad de la cuenta.
>
> 2️⃣ Incluyendo los parámetros opcionales: Se añadirá una verificación de titularidad, que puede ser True o False. Esta vendrá incluida en la response dentro de data como un campo "verification"
>
> Si es True, la cuenta pertenece al titular consultado.\
> Si es False, el servicio devolverá de igual manera los datos del titular asociado al CCI consultado.
>
> ```json Data
> {    
>    "currency": 1,
>   "beneficiary_account": "0031000170019914123",
>   "beneficiary_account_number" :"19193593257041", //Opcional
>
> }
> ```
> ```json Data & Verification
> {    
>    "currency": 1,
>    "beneficiary_account": "0031000170019914123", 
>    "beneficiary_account_number" :"19193593257041", //Opcional
>    "beneficiary_id": "{{id}}", //Opcional
>    "beneficiary_name":" {{name}}",//Opcional
>    "beneficiary_bank": "{{name}", //}Opcional 
>    "beneficiary_doc_type": {{int}} , Opcional
> }
> ```

**Respuestas esperadas**

```json Data
{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxx-a2d5-49a3-bb9xxx2-xxxxxx",
    "data": {
        "currency": 1,
        "beneficiary_name": "Alejandro Poblete Fernandez",
        "beneficiary_bank": "Banco Falabella",
        "beneficiary_doc_type": "1",
        "beneficiary_id": "****1111",
        "plaza": "LIMA"
    }
}
```
```json Data & Verification
{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxx-a2d5-49a3-bb9xxx2-xxxxxx",
    "data": {
        "currency": 1,
        "beneficiary_name": "Alejandro Poblete Fernandez",
        "beneficiary_bank": "Banco Falabella",
        "beneficiary_doc_type": "1",
        "beneficiary_id": "****1111",
        "validation": true,
        "plaza": "LIMA"
    }
}
```

**CUENTAS BCP**

**Descripción:** Este método se utiliza para realizar la verificación de una cuenta. Este payload de ejemplo es para validar cuentas de **Banco BCP**

**Body de la Solicitud (cuentas BCP):**

```json Perú
{    
  "currency": 1,
  "beneficiary_account": "00219119359325704155",
  //"account_sub_type": "3", Opcional, por defecto si no se envía se usará "cuenta de ahorro"
  //"beneficiary_id": "{{id}}", Opcional
  //"beneficiary_doc_type":{{int}} , Opcional
}
```

**Parámetros de Ruta:**

[block:parameters]
{
  "data": {
    "h-0": "Parámetro",
    "h-1": "Descripción",
    "h-2": "Tipo",
    "h-3": "In/Out",
    "h-4": "Longitud",
    "0-0": "`currency`",
    "0-1": "Es el código de moneda (1 Soles, 2 Dólares  \namericanos). ",
    "0-2": "Short ",
    "0-3": "In ",
    "0-4": "4.0",
    "1-0": "`beneficiary_account`",
    "1-1": "Es el código de cuenta interbancario (CCI) del beneficiario final. Este Código de Cuenta Interbancario, tiene 20 dígitos, compuesto así: Código de la Entidad Financiera: 3 dígitos. Código de la oficina: 3 dígitos. Número de la cuenta: 12 dígitos.",
    "1-2": "String",
    "1-3": "In",
    "1-4": "20",
    "2-0": "`beneficiary_account_number`(opcional)",
    "2-1": "Código de cuenta BCP a consultar",
    "2-2": "String",
    "2-3": "In",
    "2-4": "20",
    "3-0": "`beneficiary_id`(opcional)",
    "3-1": "Opcional. DNI del titular de la cuenta.",
    "3-2": "String",
    "3-3": "In",
    "3-4": "15",
    "4-0": "`beneficiary_doc_type (opcional)`",
    "4-1": "Opcional. Tipo de documento del titular de la cuenta.  \nLos tipos de doc aceptados para validación son:  \n  \n1 DNI  \n2 Carnet de extranjería  \n9 RUC",
    "4-2": "String",
    "4-3": "In",
    "4-4": "2",
    "5-0": "`account_sub_type`",
    "5-1": "Información/detalle adicional sobre la cuenta a validar en caso de que se valide si la cuenta pertenece a una persona o empresa  \n  \n  '1' =>  Cuenta Corriente  \n  '2' =>  Cuenta Maestra  \n  '3' =>  Cuenta de Ahorro  \n  '4' => CTS",
    "5-2": "String",
    "5-3": "In",
    "5-4": "2"
  },
  "cols": 5,
  "rows": 6,
  "align": [
    "left",
    "left",
    "left",
    "left",
    "left"
  ]
}
[/block]

> ✅ Tienes cuatro formas de realizar la solicitud para este servicio de validación:
>
> 1. Usando solo los parámetros obligatorios.
> 2. Incluyendo los parámetros opcionales: Se añadirá una verificación de titularidad, que puede ser True o False. Esta vendrá incluida en la response dentro de data como un campo "validation"
>
> Si es True, la cuenta pertenece al titular consultado.\
> Si es False, el servicio devolverá de igual manera los datos del titular asociado al CCI consultado.
>
> 3. Si no se dispone del cci se puede enviar directamente el número de cuenta BCP para la validación de la cuenta, para esto se dispone del input "beneficiary\_account\_number"
> 4. Usando el número de cuenta para la validación de titularidad
>
> ```json Data
> {    
>   "currency": 1,
>   "beneficiary_account": "0031000170019914123" //cci
>   //"account_sub_type": "{{type}}", opcional
> }
> ```
> ```json Data & Verification
> {    
>    "currency": 1,
>    "beneficiary_account": "0031000170019914123", //cci
>    "beneficiary_id": "{{id}}", //Opcional
>    "beneficiary_name":" {{name}}",//Opcional
>    "beneficiary_doc_type": {{int}} , Opcional
> }
> ```
> ```Text Data con número de cuenta
> {
>   "currency": 1,
>   "beneficiary_account_number": "19193593257041" //número de cuenta bcp
>   //"account_sub_type": "{{type}}", opcional
> }
> ```
> ```Text Data & Verification con número de cuenta
> {    
>    "currency": 1,
>    "beneficiary_account_number": "19193593257041" //número de cuenta bcp
>    "beneficiary_id": "{{id}}", //Opcional
>    "beneficiary_name":" {{name}}",//Opcional
>    "beneficiary_bank": "{{name}", //}Opcional 
>    "beneficiary_doc_type": {{int}} , Opcional
> }
> ```

**Respuestas esperadas**

```json Data Ok
{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxxx-xxxx-xxxx",
    "data": {
        "BeneficiaryBank": "Banco De Crédito Del Perú"
    }
}
```
```json Data & Verification OK
{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxxx-xxxx-xxxx",
    "data": {
        "BeneficiaryBank": "Banco De Crédito Del Perú",
        "BeneficiaryDocType": 1,
      	"BeneficiaryDocument": "74029573",
			"validation: "true"

    }
}
```
```Text Data no ok
{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxxx-xxxx-xxx",
    "data": {
        "validation": false
    }
}
```
```Text Moneda incorrecta
{
    "code": 200,
    "msg": "Moneda incorrecta",
    "caseid": "xxx-7703-xx-91fc-xxx",
    "data": {
        "validation": false
    }
}
```

**Parámetros de Ruta:**

**Bancos disponibles para validación:**

* Falabella
* BCP
* 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

```json json
{
  "code": Int,
  "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**

```json 400
{
  "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":"xxxxxxxx"
}
```
```json 400
{
  "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":"xxxxxx"
}
```
```json 400
{
  "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":"xxxxxxxxxxx"
}
```
```json 400
{
  "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"
}
```
```json 400
{
  "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"
}
```
```json 429
{
  "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"
}
```
```json 481
{
  "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"
}
```
```json 400
{
    "code": 400,
    "error_type": "BANK_ERROR",
    "error_code": "BANK_DOWN",
    "error_message": "the bank is not responding, either for maintenance or due to an issue with their systems",
    "display_message": "El banco no está respondiendo correctamente por el momento, favor intente nuevamente más tarde. ",
    "caseid": "xxxxxxxxxx"
}
```
```json 400
{
    "code": 400,
    "error_type": "INVALID_BENFICIARY_CURRENCY_ERROR",
    "error_code": "INVALID_BENFICIARY_CURRENCY",
    "error_message": "Currency inválido. Asegúrese que el currency sea el correcto",
    "display_message": "Invalid Currency. Make sure the currency is correct.",
    "caseid": "xxxxxxxxxxxxx"
}
```
```json 400
{
    "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": "xxxxxxxxxx"
}
```

### Códigos de Error

**Errores de Servicio**

| Parámetro Code | MSJ              | Description                                                             |
| :------------- | :--------------- | :---------------------------------------------------------------------- |
| `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. |

| Parámetro Code | MSJ                  | Description                                                                     |
| :------------- | :------------------- | :------------------------------------------------------------------------------ |
| `400`          | INVALID\_REQUEST     | La solicitud contiene parámetros inválidos o faltantes.                         |
| `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. |
| `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.                                        |

## Sandbox

El servicio de Validación de cuentas en el entorno sandbox permite la gestión de pagos automáticos con fines de prueba y desarrollo.

**Exitoso: CCI 11111111111111111111**

```json Body
{
    "currency": 1,
    "beneficiary_account": "11111111111111111111",
    "sandbox" : "true"
}
```

```json Response 200
{
    "code": 200,
    "msg": "OK",
    "caseid": "8da0b24f-2495-4b15-99ec-2490c78747a8",
    "data": {
        "currency": 1,
        "beneficiary_name": "FLOID PERU S A C",
        "beneficiary_bank": "Banco Alfin",
        "beneficiary_doc_type": "2",
        "beneficiary_id": "20607677001"
    }
}
```

**Exitoso: CCI 22222222222222222222**

```json Body
{
    "currency": 2,
    "beneficiary_account": "22222222222222222222",
    "sandbox" : "true"
}
```

```json Response 200
{
    "code": 200,
    "msg": "OK",
    "caseid": "8da0b24f-2495-4b15-99ec-2490c78747a8",
    "data": {
        "currency": 1,
        "beneficiary_name": "Empresa S A C",
        "beneficiary_bank": "Banco",
        "beneficiary_doc_type": "2",
        "beneficiary_id": "222222222222"
    }
}
```

**Error CCI Incorrecto: CCI 12345678901234561890**

```json Body
{
    "currency": 1,
    "beneficiary_account": "12345678901234561890",
    "sandbox" : "true"
}
```

```json Response Error
{
    "code": 404,
    "error_type": "CCI_NOT_FOUND_ERROR",
    "error_code": "CCI_NOT_FOUND",
    "error_message": "CCI no encontrado",
    "display_message": "CCI not found",
    "caseid": "xxxx-xxxxx-xxx-xxx"
}
```