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.

Delivery is attempted up to 3 times per event. Any HTTP 2xx response counts as successful delivery.

Parameters

Request body

Request example

{
  "feature_id": "11111111-1111-1111-1111-111111111111",
  "destination_kind": "EXTERNAL_WEBHOOK",
  "scope_kind": "TENANT",
  "webhook_url": "https://example.com/hooks/tilopay",
  "secret_ref": "whsec_example_shared_secret"
}

{
  "success": true,
  "http_status_code": 201,
  "response_code": "CREATED",
  "message": "The resource was created successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "feature_id": "11111111-1111-1111-1111-111111111111",
    "is_enabled": true,
    "destination_kind": "EXTERNAL_WEBHOOK",
    "destination_ref": null,
    "webhook_url": "https://example.com/hooks/tilopay",
    "secret_ref": "whsec_example_shared_secret",
    "signature_algo": "AES_GCM",
    "replay_window_sec": null,
    "timeout_ms": 10000,
    "max_attempts": 8,
    "scope_kind": "TENANT",
    "scope_account_id": null,
    "scope_owner_type": null,
    "scope_owner_id": null,
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z"
  }
}

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

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "items": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "event_types": [
          "payin.posted",
          "payment.succeeded",
          "payment.failed",
          "payment.reversed"
        ]
      }
    ]
  }
}

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

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}; the decrypted plaintext matches that contract.

`rejection.code` values

Delivery is attempted up to 3 times per event. Any HTTP 2xx response counts as successful delivery.

Parameters

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "event_type": "payment.succeeded",
    "schema_version": "1.0.0",
    "description": "Envelope delivered for `payment.succeeded` (decrypt AES_GCM `data` field first).",
    "example": {
      "event_id": "evt_01JEXAMPLE",
      "event_type": "payment.succeeded",
      "schema_version": "1.0.0"
    },
    "x-description-es": "Sobre entregado para `payment.succeeded` (descifrá primero el campo `data` AES_GCM)."
  }
}

Error responses