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 🟠

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):

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

Parámetro	Descripción	Tipo	In/Out	Longitud
`currency`	Es el código de moneda (1 Soles, 2 Dólares americanos).	Short	In	4.0
`beneficiary_account`	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.	String	In	20
`beneficiary_id`	Opcional. DNI del titular de la cuenta.	String	In	15
`beneficiary_name`	Opcional. Nombre del titular de la cuenta.	String	In	30
`beneficiary_bank`	Opcional. Nombre del banco de la cuenta que se requiere verificar.	String	In	20
`beneficiary_doc_type`	Opcional. Tipo de documento del titular de la cuenta. Los tipos de doc aceptados para validación son: 1 DNI 2 Carnet de extranjería 9 RUC	Int	In	2
`custom`(opcional)	Información/detalle adicional sobre la transacción. Se muestra en el dashboard	String	In	50

✅
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.
{    
   "currency": 1,
  "beneficiary_account": "0031000170019914123",
  "beneficiary_account_number" :"19193593257041", //Opcional

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

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

{
    "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):

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

Parámetro	Descripción	Tipo	In/Out	Longitud
`currency`	Es el código de moneda (1 Soles, 2 Dólares americanos).	Short	In	4.0
`beneficiary_account`	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.	String	In	20
`beneficiary_account_number`(opcional)	Código de cuenta BCP a consultar	String	In	20
`beneficiary_id`(opcional)	Opcional. DNI del titular de la cuenta.	String	In	15
`beneficiary_doc_type (opcional)`	Opcional. Tipo de documento del titular de la cuenta. Los tipos de doc aceptados para validación son: 1 DNI 2 Carnet de extranjería 9 RUC	String	In	2
`account_sub_type`	Información/detalle adicional sobre la cuenta a validar en caso de que se valide si la cuenta pertenece a una persona o empresa '1' => Cuenta Corriente '2' => Cuenta Maestra '3' => Cuenta de Ahorro '4' => CTS	String	In	2

✅
Tienes cuatro formas de realizar la solicitud para este servicio de validación:

Usando solo los parámetros obligatorios.

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.

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"

Usando el número de cuenta para la validación de titularidad
{    
  "currency": 1,
  "beneficiary_account": "0031000170019914123" //cci
  //"account_sub_type": "{{type}}", opcional
}
{    
   "currency": 1,
   "beneficiary_account": "0031000170019914123", //cci
   "beneficiary_id": "{{id}}", //Opcional
   "beneficiary_name":" {{name}}",//Opcional
   "beneficiary_doc_type": {{int}} , Opcional
}
{
  "currency": 1,
  "beneficiary_account_number": "19193593257041" //número de cuenta bcp
  //"account_sub_type": "{{type}}", opcional
}
{    
   "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

{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxxx-xxxx-xxxx",
    "data": {
        "BeneficiaryBank": "Banco De Crédito Del Perú"
    }
}

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

    }
}

{
    "code": 200,
    "msg": "OK",
    "caseid": "xxxxx-xxxx-xxx",
    "data": {
        "validation": false
    }
}

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

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

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

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

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

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

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

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

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

Validación de Cuenta Yape

Este servicio permite validar si un número telefónico está asociado a una cuenta Yape válida.

Descripción

El endpoint recibe el número de celular del beneficiario y retorna si la cuenta Yape asociada existe y se encuentra habilitada para operar.

Este flujo es útil para validar cuentas antes de ejecutar operaciones posteriores, como pagos, transferencias o registro de beneficiarios.

Endpoint

POST /yape/account/validate

Reemplaza la ruta por la URL real del ambiente correspondiente.

Autenticación

El servicio requiere autenticación mediante token.

Authorization: Bearer <access_token>
Content-Type: application/json

Parámetros de solicitud

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`beneficiary_account`	`string`	Sí	Número telefónico asociado a la cuenta Yape que se desea validar. Debe incluir el prefijo del país.	`51912345678`

Request

{
  "beneficiary_account": "51912345678"
}

Responses

Cuenta válida

Cuando el número telefónico tiene una cuenta Yape válida, el servicio retorna valid: true.

{
  "code": 200,
  "msg": "OK",
  "caseid": "xxxx-xxxxx-xxx-xxx",
  "data": {
    "valid": true
  }
}

Cuenta inválida

Cuando el número telefónico no tiene una cuenta Yape válida, el servicio retorna valid: false junto con el motivo.

{
  "code": 200,
  "msg": "OK",
  "caseid": "xxxx-xxxxx-xxx-xxx",
  "data": {
    "valid": false,
    "reason": "El teléfono no tiene una cuenta Yape válida"
  }
}

Campos de respuesta

Campo	Tipo	Descripción
`code`	`number`	Código interno de respuesta del servicio.
`msg`	`string`	Mensaje general de la operación.
`caseid`	`string`	Identificador único de trazabilidad para la solicitud.
`data.valid`	`boolean`	Indica si el número telefónico tiene una cuenta Yape válida.
`data.reason`	`string`	Motivo por el cual la cuenta no es válida. Solo se retorna cuando `valid` es `false`.

Códigos de estado

Código HTTP	Descripción
`200`	Solicitud procesada correctamente. La validez de la cuenta se informa en `data.valid`.
`400`	Solicitud inválida. Verifica el formato de los parámetros enviados.
`401`	Token de autenticación inválido o ausente.
`500`	Error interno del servicio.

Validaciones recomendadas

Antes de consumir el servicio, se recomienda validar que:

beneficiary_account no esté vacío.
El número tenga formato numérico.
El número incluya el prefijo de país, por ejemplo 51 para Perú.
El número tenga la longitud esperada para el país correspondiente.

Ejemplo con cURL

curl --location --request POST 'https://api.example.com/yape/account/validate' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "beneficiary_account": "51912345678"
  }'

Manejo de respuesta recomendado

const response = await validateYapeAccount({
  beneficiary_account: '51912345678'
});

if (response.data.valid) {
  // Continuar con el flujo de operación
} else {
  // Mostrar el motivo al usuario o detener el proceso
  console.log(response.data.reason);
}

Notas

Una respuesta HTTP 200 no significa necesariamente que la cuenta sea válida.
La validez de la cuenta debe evaluarse usando el campo data.valid.
El campo caseid debe conservarse para seguimiento, auditoría o soporte.

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 12345678901234567890

{
    "currency": 1,
    "beneficiary_account": "12345678901234567890",
    "sandbox" : "true"
}

{
    "code": 200,
    "msg": "OK",
    "data": {
        "currency": 1,
        "beneficiary_name": "ALEJANDRO JOSÉ FERNANDEZ POBLETE",
        "beneficiary_bank": "BBVA",
        "beneficiary_doc_type": "2",
        "beneficiary_id": "42662123"
    }
}

Exitoso: CCI 11111111111111111111

{
    "currency": 1,
    "beneficiary_account": "11111111111111111111",
    "sandbox" : "true"
}

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

{
    "currency": 1,
    "beneficiary_account": "22222222222222222222",
    "sandbox" : "true"
}

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

{
    "currency": 1,
    "beneficiary_account": "12345678901234561890",
    "sandbox" : "true"
}

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

Validación de Cuenta Perú

Perú

✅
Tienes dos formas de realizar la solicitud para este servicio de validación:

✅
Tienes cuatro formas de realizar la solicitud para este servicio de validación:

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

Validación de Cuenta Yape

Descripción

Endpoint

Autenticación

Parámetros de solicitud

Request

Responses

Cuenta válida

Cuenta inválida

Campos de respuesta

Códigos de estado

Validaciones recomendadas

Ejemplo con cURL

Manejo de respuesta recomendado

Notas

Sandbox

Perú

✅Tienes dos formas de realizar la solicitud para este servicio de validación:

✅Tienes cuatro formas de realizar la solicitud para este servicio de validación:

5. Manejo de Errores

Estructura de Respuesta de Error

Códigos de Error

Validación de Cuenta Yape

Descripción

Endpoint

Autenticación

Parámetros de solicitud

Request

Responses

Cuenta válida

Cuenta inválida

Campos de respuesta

Códigos de estado

Validaciones recomendadas

Ejemplo con cURL

Manejo de respuesta recomendado

Notas

Sandbox

✅
Tienes dos formas de realizar la solicitud para este servicio de validación:

✅
Tienes cuatro formas de realizar la solicitud para este servicio de validación: