Banking API payments

List customer payments

GET /api/public/v1/transactions/payments

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

Simple REST list of payments for an owned account (IBAN).

Filters are query parameters. Ownership (tenant_id, owner_type, owner_id) is derived from the access token; clients must not send ownership filters.

Account identification (required): type + value (identifier scheme + value, e.g. IBAN + IBAN string). This is not the internal account classification.

Pagination is cursor-based (limit, cursor). Default limit is 20 (max 100).

status in the response and as a filter uses the public lowercase catalog (pending, processing, confirmed, posted, failed). Same values as webhooks. REST also returns status_detail (uppercase operational name).

Each item includes a consolidated result (succeeded, failed, reversed, pending) for reconciliation when a webhook was missed. status is only the processing/lifecycle catalog and does not change to failed when a posted payment is later reversed — use result=reversed and has_reversal=true (webhook payment.reversed). error is null when there is no failure information; it is an object only when domain / platform is present (result is failed or reversed), same shape as webhook payment.failed payment.error. source / destination use null for unknown account, name, and identification; account values are IBAN or PHONE only (never ledger UUIDs). For PIN payments created after public identification persistence, identification.number is the partner-submitted public number (no SINPE hyphens); older payments may still show the hyphenated SINPE form. See docs/PAYMENT-IDENTIFICATION.md.

Parameters

Error responses

Create payment

POST /api/public/v1/transactions/payments

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

Creates a payment using an authorized internal source account. Processing may be asynchronous; HTTP 201 does not imply the payment is finalized. source.identification.number and destination.identification.number are stored in public form (the submitted digits, without SINPE hyphens) and returned on later payment reads. The GX/SINPE hyphenated form is used only internally and is not the public contract. Idempotency-Key is optional; if omitted, each request is treated as a new attempt. A repeated client_reference returns 409 PAYMENT_DUPLICATE when an in-flight or completed payment already uses it; a prior failed (or rejected/cancelled/expired) payment does not block a retry with the same client_reference. If Idempotency-Key is provided, the same key with the same payload replays the prior response; a different payload with the same key returns 409 IDEMPOTENCY_CONFLICT.

Parameters

Request body

Error responses

Search payment by identifier

POST /api/public/v1/transactions/payments/search

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

Looks up a single payment within the supplied customer account by exactly one of:

• payment_id (internal UUID)
• public_id (numeric public identifier)
• client_reference (partner reference sent at creation)

Sending more than one identifier returns 400. Response shape matches get-by-id (schema_version, payment-level external_reference, shared provider object, provider.provider_status_*, webhook-aligned error). Same public contract as GET /transactions/payments, including public identification.number for PIN payments created after public identification persistence. If several payments share a client_reference (failed attempt plus retry), the in-flight or completed payment is returned when one exists.

Parameters

Request body

Request example

{
  "account": {
    "type": "IBAN",
    "value": "CR08036900101010933608"
  },
  "payment_id": "11111111-1111-1111-1111-111111111111"
}

{
  "account": {
    "type": "IBAN",
    "value": "CR08036900101010933608"
  },
  "public_id": "134729"
}

{
  "account": {
    "type": "IBAN",
    "value": "CR08036900101010933608"
  },
  "client_reference": "INV-01082"
}

Error responses

Get payment by id

GET /api/public/v1/transactions/payments/{payment_id}

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

Returns a single payment using the same public contract as the list endpoint, including consolidated result, succeeded_at, has_reversal, and error. error is null when there is no failure information; it is an object only when domain / platform is present (result is failed or reversed), same shape as webhook payment.failed payment.error. source / destination use null for unknown nested fields and never expose ledger UUIDs. identification.number on PIN payments created after public identification persistence is the partner-submitted public number (digits, no SINPE hyphens). Older payments may still return the hyphenated SINPE form from processing metadata. Use this as a webhook backup.

Looks up a payment by either identifier:

• payment_id (internal UUID)
• public_id (numeric public identifier)

For client_reference, use POST /api/public/v1/transactions/payments/search.

Parameters

Error responses

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 ledger 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 backing wallet operation (ObtenerInfoMonedero) 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 (ObtenerInformacionCuentaSinpe) 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 WebhookRejection.code schema enum). 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.

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)

⚠️ This catalog is under review — some entries (notably 208 and 209) are known to be pending verification against the official SINPE source and may be corrected in a future revision without notice.

Parameters

Request body

Request example

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

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

Error responses