Banking API accounts

Validate external account for a payment method

POST /api/public/v1/accounts/validate

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

Validates a counterparty account (IBAN or phone) via the SINPE provider for the given payment method. Does not validate internal platform accounts. When valid, data.holder.id_type uses the same identification catalog keys as identification.type in POST /payments (e.g. cedula, juridica, dimex).

SINPE_MOVIL field availability (expected, stable)

For payment_method_code = SINPE_MOVIL, the SINPE Móvil wallet query does not return identification type or institution name. A successful validation may therefore return:

• data.holder.id_type = unknown
• data.financial_institution.entity_name = "" (empty string)

This is expected, stable behavior, not a mapping bug or a transient provider error. PIN (account query in SINPE) does populate both fields.

Integrators must not report these values as defects, and must not assume that holder.id_type or financial_institution.entity_name are always populated when is_valid is true.

SINPE rejection codes (data.rejection)

When is_valid is false, data.rejection explains why (see the rejected example on the 200 response below). rejection.code is one of a fixed set of normalized semantics (see the value table below). Most rows in the table below do NOT get a distinct `code` — only a subset of reason_code values has a dedicated semantic; every other reason_code, even one listed below with a specific message, returns code = SINPE_REJECTED (e.g. reason_code = 21 "fondos insuficientes" still returns SINPE_REJECTED). This same object and catalog is also used by the payment.failed webhook's rejection field. A reason_code not listed here at all still produces a response — message falls back to a generic text and code falls back to SINPE_REJECTED.

Account / profile / limits

Settlement with destination institution

Identification

Format validation / Core Banking

Channel / identification type

SINPE Móvil (wallet)

`rejection.code` values

Rate limits currently apply to authentication and account validation. Exceeding them returns HTTP 429 (TOO_MANY_REQUESTS). Retry with exponential backoff.

SINPE code 1001 means the account exists and is active; it is a valid result, not a rejection reason.

Parameters

Request body

Request example

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

Error responses

List balances for accessible accounts

GET /api/public/v1/accounts/balances

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

Returns paginated account balances (account, amounts, as_of). This endpoint checks the current balance in real time and may respond more slowly than GET /accounts. For account attributes without amounts, use GET /accounts.

Optional filters use the public account identification standard: type + value (identifier scheme + value). type is not the internal account classification.

Parameters

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

Error responses

List accessible accounts without balances

GET /api/public/v1/accounts

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

Returns paginated accessible accounts without querying current balances. Each item is account attributes only (account.type, account.value, account.currency). amounts and as_of are not included; use GET /accounts/balances or POST /accounts/balance.

Optional filters use the public account identification standard: type + value (identifier scheme + value). type is not the internal account classification.

Parameters

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

Error responses

Get account balance

POST /api/public/v1/accounts/balance

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

Returns a single account snapshot with amounts and as_of. For account attributes without balances, use GET /accounts.

Parameters

Request body

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

Error responses

Request account statement generation

POST /api/public/v1/accounts/statements

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

Creates an asynchronous account statement request for a date range (max 60 days). Identify the account with account.type + account.value (identifier scheme + value, e.g. IBAN). This follows the public account identification standard. account.type is not the internal account classification. Returns {request_id, status: PENDING} immediately. Poll GET /accounts/statements/{request_id} for status; when DONE, the response includes a signed download_url.

Always returns HTTP 202 (ACCEPTED) with request_id and status PENDING. Generation is asynchronous. Poll GET /api/public/v1/accounts/statements/{request_id}: HTTP 200 with PENDING, PROCESSING, DONE or ERROR. DONE includes download_url, valid for 48 hours.

Parameters

Request body

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

Error responses

Get account statement request status

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

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

Returns request status. When DONE, includes a signed, time-limited download_url (48h from generation) and expires_at. When ERROR, includes a generic message without internal details. Unknown or unauthorized request_id returns 404.

Returns HTTP 200 with status PENDING, PROCESSING, DONE or ERROR. DONE includes download_url, valid for 48 hours.

Parameters

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

Error responses