Banking API webhooks

Create webhook destination

POST /api/public/v1/webhook/destination

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

Valid fields depend on destination_kind and scope_kind. Send only the fields that apply to your combination; other scope fields must be omitted (not null placeholders).

Event payloads Inspect outbound contracts with GET /api/public/v1/webhook/event-contracts/{event_type} (payin.posted, payment.succeeded, payment.failed, payment.reversed).

destination_kind

• EXTERNAL_WEBHOOK (only kind available on the public API): requires webhook_url (must start with https://) and secret_ref. Optional delivery tuning (timeout_ms, max_attempts). Payloads are always encrypted with AES_GCM using secret_ref; the HTTP body is {"data":"<ciphertext>"}.
• INTERNAL is reserved for platform administration and cannot be created through this endpoint.

scope_kind

• TENANT: omit scope_account_id, scope_owner_type, and scope_owner_id.
• ACCOUNT: require scope_account_id; omit owner fields.
• OWNER: require scope_owner_type and scope_owner_id; omit scope_account_id. scope_owner_type is one of tenant, partner, user, platform, customer (lowercase in payload).

Webhook encryption (EXTERNAL_WEBHOOK)

Deliveries always send Content-Type: application/json and Accept: application/json.

The HTTP body is always {"data": "<base64>"}. The base64-decoded bytes are:

nonce (12 bytes, random) || AES-256-GCM ciphertext || 16-byte auth tag

key                   = SHA256(secret_ref)              # 32 bytes → AES-256
wire                  = base64_decode(data)
nonce, sealed         = wire[:12], wire[12:]             # sealed = ciphertext || tag
plaintext             = AES-GCM-Open(key, nonce, sealed, additional_data = none)

No additional authenticated data (AAD) is used. plaintext is the same JSON envelope documented per event type in GET /webhook/event-contracts/{event_type} — decrypt first, then apply that contract. Authenticity is provided by the GCM auth tag (decryption fails if the body was tampered with).

Deduplicate retries using event.event_id in the payload envelope — delivery retries can redeliver the same event with the same event_id.

Parameters

Request body

Request example

{
  "feature_id": "11111111-1111-1111-1111-111111111111",
  "destination_kind": "EXTERNAL_WEBHOOK",
  "scope_kind": "TENANT"
}

Error responses

List webhook features by payment method

GET /api/public/v1/webhook/features

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

Returns feature IDs and the event_types each feature can emit. Tenant scope is taken from the access token; clients must not send tenant_id.

Naming: event_types use payment.* for resource-level outcomes (payment.succeeded, payment.failed, payment.reversed) and payin.posted for the inbound direction only (funds received). There is no payout.posted and no transaction.* events. The delivered JSON object is always payment.

Inspect payload shapes with GET /api/public/v1/webhook/event-contracts/{event_type} (payin.posted, payment.succeeded, payment.failed, payment.reversed).

Parameters

Error responses

Webhook event contract

GET /api/public/v1/webhook/event-contracts/{event_type}

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

Returns the outbound webhook payload contract for one public event type (schema_version 1.0.0). The envelope object is always payment (never payin, payout, or transaction).

When to use each name

• payment — resource and envelope. Outcome events: payment.succeeded, payment.failed, payment.reversed (both PAYIN and PAYOUT). Correlate with REST /transactions/payments.
• payin / payout — direction (PAYIN inbound, PAYOUT outbound). payin.posted is inbound-only (ledger posted / funds received). There is no public payout.posted.
• transaction — REST path prefix only. Not used in webhook event_type or payload objects.

Supported event_type values:

• payin.posted — inbound (PAYIN) payment reached public status posted. Envelope field is payment. payment.local_payment is a JSON boolean (true/false), not a string.
• payment.succeeded — the provider confirmed success for a payment (PAYIN or PAYOUT; PIN or SINPE Móvil). Resource-level outcome, not direction-specific.
• payment.failed — processing ended in a definitive failure (public status=failed), with structured payment.error (domain / platform). When the provider rejected the payment, the envelope also includes rejection. Not used for later reversals.
• payment.reversed — subsequent reversal of a payment that already progressed (typically status=posted or confirmed). REST result=reversed and has_reversal=true. Processing status is unchanged. Not a payment.failed.

Unknown event_type values (including internal-only payment.status_changed) return 404.

SINPE rejection codes (rejection, only on payment.failed)

When event_type = payment.failed and the provider rejected the payment, the envelope includes rejection (same object and catalog as data.rejection on POST /accounts/validate). 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). 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.

Delivery body is JSON. EXTERNAL_WEBHOOK HTTP body is always {"data":"<ciphertext>"} (AES-256-GCM, key = SHA256(secret_ref)). Decrypt to obtain the event envelope documented per GET /webhook/event-contracts/{event_type}. and the decrypted plaintext matches this contract.

Parameters

Error responses