Cuentas del API Bancario

Validar cuenta externa para un método de pago

POST /api/public/v1/accounts/validate

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>.

Valida una cuenta de beneficiario (IBAN o teléfono) a través del proveedor SINPE para el método de pago indicado. No valida cuentas internas de la plataforma. Cuando es válida, data.holder.id_type usa las mismas claves del catálogo de identificación que identification.type en POST /payments (ej. cedula, juridica, dimex).

Disponibilidad de campos en SINPE_MOVIL (esperado, estable)

Para payment_method_code = SINPE_MOVIL, la consulta del monedero SINPE Móvil no devuelve el tipo de identificación ni el nombre de la entidad. Una validación exitosa puede entonces devolver:

• data.holder.id_type = unknown
• data.financial_institution.entity_name = "" (cadena vacía)

Este comportamiento es esperado y estable, no un error de mapeo ni un error transitorio del proveedor. PIN (la consulta de la cuenta en SINPE) sí completa ambos campos.

No reportés estos valores como defectos ni asumás que holder.id_type o financial_institution.entity_name siempre vienen completos cuando is_valid es true.

Códigos de rechazo SINPE (data.rejection)

Cuando is_valid es false, data.rejection explica por qué (ver el ejemplo rejected en la respuesta 200 más abajo). rejection.code es uno de un conjunto fijo de semánticas normalizadas (ver la tabla de valores más abajo). La mayoría de filas de la tabla NO tienen un `code` propio: solo un subconjunto de valores de reason_code tiene una semántica dedicada; cualquier otro reason_code, incluso uno listado abajo con un message específico, devuelve code = SINPE_REJECTED (ej. reason_code = 21 "fondos insuficientes" igual devuelve SINPE_REJECTED). Este mismo objeto y catálogo los usa también el campo rejection del webhook payment.failed. Un reason_code que no aparece aquí igual produce respuesta: message cae a un texto genérico y code a SINPE_REJECTED.

Cuenta / perfil / límites

Compensación con entidad destino

Identificación

Validación de formato / Core Bancario

Canal / tipo de identificación

SINPE Móvil (monedero)

Valores de `rejection.code`

Actualmente hay límites de tasa en autenticación y validación de cuentas. Superarlos devuelve HTTP 429 (TOO_MANY_REQUESTS). Reintentá con espera exponencial.

El código SINPE 1001 indica que la cuenta existe y está activa; es un resultado válido, no un motivo de rechazo.

Parámetros

Cuerpo del request

Ejemplo de request

{
  "payment_method_code": "PIN",
  "account": {
    "type": "IBAN",
    "value": "CR16010400000000000031"
  }
}

{
  "payment_method_code": "SINPE_MOVIL",
  "account": {
    "type": "PHONE",
    "value": "88887777"
  }
}

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "is_valid": true,
    "account": {
      "type": "IBAN",
      "value": "CR16010400000000000031",
      "currency": "CRC",
      "product_name": "Cuenta corriente"
    },
    "holder": {
      "name": "Juan Perez",
      "id_type": "cedula"
    },
    "financial_institution": {
      "entity_code": "104",
      "entity_name": "Banco Ejemplo"
    },
    "provider": {
      "reason_code": "0",
      "message": "Cuenta válida",
      "code": null
    },
    "rejection": null
  }
}

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "is_valid": false,
    "account": {
      "type": "IBAN",
      "value": "CR16010400000000000099",
      "currency": "CRC",
      "product_name": ""
    },
    "holder": null,
    "financial_institution": {
      "entity_code": "104",
      "entity_name": "Banco Ejemplo"
    },
    "provider": {
      "reason_code": "28",
      "message": "Cuenta cliente no existe",
      "code": "ACCOUNT_NOT_FOUND"
    },
    "rejection": {
      "code": "ACCOUNT_NOT_FOUND",
      "reason_code": "28",
      "message": "Cuenta cliente no existe"
    }
  }
}

Respuestas de error

Listar saldos de las cuentas accesibles

GET /api/public/v1/accounts/balances

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>.

Devuelve los saldos paginados de las cuentas (account, amounts, as_of). Este endpoint consulta el saldo actual en tiempo real y puede responder más lento que GET /accounts. Para los atributos de la cuenta sin montos, usá GET /accounts.

Los filtros opcionales usan el estándar público de identificación de cuentas: type + value (esquema de identificación + valor). type no es la clasificación interna de la cuenta.

Parámetros

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "items": [
      {
        "account": {
          "type": "IBAN",
          "value": "CR26036900101010588061",
          "currency": "CRC"
        },
        "amounts": {
          "available": "991900.00",
          "posted": "991900.00",
          "inbound_in_transit": "0.00",
          "outbound_in_transit": "0.00"
        },
        "as_of": "2026-01-15T12:00:00Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 1
    }
  }
}

Respuestas de error

Listar cuentas accesibles sin saldos

GET /api/public/v1/accounts

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>.

Devuelve las cuentas accesibles paginadas sin consultar saldos actuales. Cada ítem trae solo atributos de la cuenta (account.type, account.value, account.currency). No incluye amounts ni as_of; usá GET /accounts/balances o POST /accounts/balance.

Los filtros opcionales usan el estándar público de identificación de cuentas: type + value (esquema de identificación + valor). type no es la clasificación interna de la cuenta.

Parámetros

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "items": [
      {
        "account": {
          "type": "IBAN",
          "value": "CR26036900101010588061",
          "currency": "CRC"
        }
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 1
    }
  }
}

Respuestas de error

Obtener saldo de una cuenta

POST /api/public/v1/accounts/balance

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>.

Devuelve la foto actual de una cuenta con amounts y as_of. Para los atributos de la cuenta sin saldos, usá GET /accounts.

Parámetros

Cuerpo del request

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "account": {
      "type": "IBAN",
      "value": "CR26036900101010588061",
      "currency": "CRC"
    },
    "amounts": {
      "available": "991900.00",
      "posted": "991900.00",
      "inbound_in_transit": "0.00",
      "outbound_in_transit": "0.00"
    },
    "as_of": "2026-01-15T12:00:00Z"
  }
}

Respuestas de error

Solicitar generación de estado de cuenta

POST /api/public/v1/accounts/statements

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>. Acepta Idempotency-Key.

Crea una solicitud asíncrona de estado de cuenta para un rango de fechas (máximo 60 días). Identificá la cuenta con account.type + account.value (esquema de identificación + valor, ej. IBAN). Sigue el estándar público de identificación de cuentas. account.type no es la clasificación interna de la cuenta. Devuelve {request_id, status: PENDING} de inmediato. Consultá GET /accounts/statements/{request_id} para el estado; cuando es DONE, la respuesta incluye una download_url firmada.

Siempre devuelve HTTP 202 (ACCEPTED) con request_id y status PENDING. La generación es asíncrona. Consultá GET /api/public/v1/accounts/statements/{request_id}: HTTP 200 con PENDING, PROCESSING, DONE o ERROR. DONE incluye download_url, válida por 48 horas.

Parámetros

Cuerpo del request

{
  "success": true,
  "http_status_code": 202,
  "response_code": "ACCEPTED",
  "message": "Statement request accepted.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "request_id": "5f3b2c1d-9e8a-4b7c-8d6e-5f4a3b2c1d0e",
    "status": "PENDING"
  }
}

Respuestas de error

Consultar estado de la solicitud de estado de cuenta

GET /api/public/v1/accounts/statements/{request_id}

Host: https://api-baas-sandbox.tilopay.com — requiere Authorization: Bearer <access_token>.

Devuelve el estado de la solicitud. Cuando es DONE, incluye una download_url firmada y temporal (48 h desde su generación) y expires_at. Cuando es ERROR, incluye un message genérico sin detalles internos. Un request_id desconocido o no autorizado devuelve 404.

Devuelve HTTP 200 con status PENDING, PROCESSING, DONE o ERROR. DONE incluye download_url, válida por 48 horas.

Parámetros

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "request_id": "5f3b2c1d-9e8a-4b7c-8d6e-5f4a3b2c1d0e",
    "status": "DONE",
    "download_url": "https://storage.example.com/statements/5f3b2c1d.pdf?signature=example",
    "expires_at": "2026-01-17T12:00:00Z",
    "message": null
  }
}

Respuestas de error