Payment Webhooks

Instead of polling Payment Status, register a webhook and Financy will
push you an update whenever the payment's status changes (e.g. it settles or
is rejected).

Configure per payment

Set callbackInformation.webhooks on the body of Create a Payment:

{
  "paymentInformation": {
    "amount": 149.90,
    "currency": "ILS",
    "description": "Order #4471"
  },
  "callbackInformation": {
    "webhooks": {
      "enabled": true,
      "successUrl": "https://your-app.com/webhooks/payment/success",
      "failUrl": "https://your-app.com/webhooks/payment/fail",
      "customHeaders": { "X-My-Token": "…" },
      "oauth": {
        "enabled": false
      }
    }
  }
}

Securing the callback with OAuth

If your webhook endpoint requires a bearer token, set oauth:

Financy fetches a token from tokenUrl and sends it as a Bearer token on the
webhook request.

💡

You can also enable webhooks globally in the Financy Dashboard (update mode)

with a success and failure URL, instead of per payment.

What Financy sends

Webhooks are always an HTTPS POST with the event data in the request body.
For a payment, the event is Payment Status Change:

{
  "paymentId": "01J8X...",
  "paymentStatus": "ACSC",
  "userId": "user-1234",
  "orgId": "org_...",
  "bankName": "Bank Hapoalim",
  "paymentError": { "message": "", "type": "" }
}

These fields are sent for every payment product. One extra field,
requestStatus, is sent for request-to-pay payments and only for those — see
below.

Request-to-pay payments

Request-to-pay (product: "request-to-pay") payments carry a second status: the
request status, which tracks the debtor's decision on the request, while
paymentStatus tracks the transfer itself. For these payments only, the webhook
body carries an extra requestStatus field, and Financy also POSTs when the
request status changes on its own — even if paymentStatus stayed the same:

{
  "paymentId": "01J8X...",
  "paymentStatus": "RCVD",
  "requestStatus": "ACCP",
  "userId": "user-1234",
  "orgId": "org_...",
  "bankName": "Bank Hapoalim"
}

A rejected request (requestStatus: "RJCT") is POSTed to your failUrl, even
while paymentStatus is still in flight — the debtor turned the request down, so
there is nothing left to wait for.

⚠️

requestStatus is sent only for request-to-pay payments. Webhook bodies

for regular payments, bulk payments and standing orders are unchanged and
never include this field, so a handler that reads it can safely treat its
absence as "this was not a request to pay".

Handling webhooks

• Respond quickly with a 2xx; do heavy work asynchronously.
• Treat the payload like a status poll: the rail's success code (or ACSC /
  ACCC) means done-OK; RJCT / CANC / ERROR means done-failed.
• Verify the request is really from Financy — check your customHeaders secret
  or the OAuth token.

📘

A separate Connection Status Change webhook fires when a linked bank's

connection changes state (e.g. reaches ACTIVE / COMPLETED, or EXPIRED) —
handy for knowing when a user's data is ready. See Connections.