Webhooks del API Bancario

Crear destino de webhook

POST /api/public/v1/webhook/destination

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

Los campos válidos dependen de destination_kind y scope_kind. Enviá solo los campos que aplican a tu combinación; los demás campos de alcance deben omitirse (no como marcadores null).

Payloads de eventos Inspeccioná los contratos salientes con GET /api/public/v1/webhook/event-contracts/{event_type} (payin.posted, payment.succeeded, payment.failed, payment.reversed).

destination_kind

• EXTERNAL_WEBHOOK (único tipo disponible en el API pública): requiere webhook_url (debe empezar con https://) y secret_ref. Ajustes opcionales de entrega (timeout_ms, max_attempts). Los payloads siempre van cifrados con AES_GCM usando secret_ref; el cuerpo HTTP es {"data":"<ciphertext>"}.
• INTERNAL está reservado para la administración de la plataforma y no puede crearse por este endpoint.

scope_kind

• TENANT: omití scope_account_id, scope_owner_type y scope_owner_id.
• ACCOUNT: enviá scope_account_id; omití los campos de owner.
• OWNER: enviá scope_owner_type y scope_owner_id; omití scope_account_id. scope_owner_type es uno de tenant, partner, user, platform, customer (en minúsculas en el payload).

Cifrado del webhook (EXTERNAL_WEBHOOK)

Las entregas siempre envían Content-Type: application/json y Accept: application/json.

El cuerpo HTTP siempre es {"data": "<base64>"}. Los bytes decodificados de base64 son:

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 se usan datos autenticados adicionales (AAD). plaintext es el mismo sobre JSON documentado por tipo de evento en GET /webhook/event-contracts/{event_type}: descifrá primero y luego aplicá ese contrato. La autenticidad la da la etiqueta de autenticación GCM (el descifrado falla si el cuerpo fue alterado).

Deduplicá los reintentos con event.event_id del sobre del payload: los reintentos de entrega pueden reenviar el mismo evento con el mismo event_id.

La entrega se intenta hasta 3 veces por evento. Cualquier respuesta HTTP 2xx se considera exitosa.

Parámetros

Cuerpo del request

Ejemplo de request

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

Respuestas de error

Listar funciones de webhook por método de pago

GET /api/public/v1/webhook/features

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

Devuelve los IDs de función y los event_types que cada una puede emitir. El alcance del comercio se toma del token de acceso; no enviés tenant_id.

Nombres: los event_types usan payment.* para resultados a nivel de recurso (payment.succeeded, payment.failed, payment.reversed) y payin.posted solo para la dirección entrante (fondos recibidos). No existe payout.posted ni eventos transaction.*. El objeto JSON entregado siempre es payment.

Inspeccioná las formas de payload con GET /api/public/v1/webhook/event-contracts/{event_type} (payin.posted, payment.succeeded, payment.failed, payment.reversed).

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": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "event_types": [
          "payin.posted",
          "payment.succeeded",
          "payment.failed",
          "payment.reversed"
        ]
      }
    ]
  }
}

Respuestas de error

Contrato de evento de webhook

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

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

Devuelve el contrato del payload saliente de webhook para un tipo de evento público (schema_version 1.0.0). El objeto del sobre siempre es payment (nunca payin, payout o transaction).

Cuándo usar cada nombre

• payment — recurso y sobre. Eventos de resultado: payment.succeeded, payment.failed, payment.reversed (tanto PAYIN como PAYOUT). Se correlaciona con /transactions/payments de REST.
• payin / payout — dirección (PAYIN entrante, PAYOUT saliente). payin.posted es solo entrante (registrado en el ledger / fondos recibidos). No existe un payout.posted público.
• transaction — solo prefijo de ruta REST. No se usa en event_type ni en los objetos del payload.

Valores de event_type admitidos:

• payin.posted — un pago entrante (PAYIN) llegó al estado público posted. El campo del sobre es payment. payment.local_payment es un booleano JSON (true/false), no una cadena.
• payment.succeeded — el proveedor confirmó el éxito de un pago (PAYIN o PAYOUT; PIN o SINPE Móvil). Resultado a nivel de recurso, no específico de dirección.
• payment.failed — el procesamiento terminó en un fallo definitivo (status=failed público), con payment.error estructurado (domain / platform). Cuando el proveedor rechazó el pago, el sobre también incluye rejection. No se usa para reversos posteriores.
• payment.reversed — reverso posterior de un pago que ya había avanzado (típicamente status=posted o confirmed). REST result=reversed y has_reversal=true. El status de procesamiento no cambia. No es un payment.failed.

Los valores de event_type desconocidos (incluido el interno payment.status_changed) devuelven 404.

Códigos de rechazo SINPE (rejection, solo en payment.failed)

Cuando event_type = payment.failed y el proveedor rechazó el pago, el sobre incluye rejection (mismo objeto y catálogo que data.rejection en POST /accounts/validate). 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). 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)

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.

Valores de `rejection.code`

La entrega se intenta hasta 3 veces por evento. Cualquier respuesta HTTP 2xx se considera exitosa.

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": {
    "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)."
  }
}

Respuestas de error