Payment Webhooks

Get notified when a payment's status changes, instead of polling.

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

Field	Description
`enabled`	Turns webhooks on for this payment.
`successUrl`	Where Financy POSTs when the payment reaches a successful state.
`failUrl`	Where Financy POSTs when the payment fails (`RJCT` / `ERROR`).
`customHeaders`	Extra headers to include on the webhook request (e.g. a shared secret).
`oauth`	Optional — secure your endpoint with an OAuth token (see below).

Securing the callback with OAuth

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

Field	Required	Description
`enabled`	–	Turn OAuth on for the callback.
`clientId`	if `enabled`	OAuth client id Financy uses to get a token.
`clientSecret`	if `enabled`	OAuth client secret.
`tokenUrl`	–	Token endpoint Financy calls.
`audience`	–	Token audience.
`scope`	–	Token scope (e.g. `read:accounts`).

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

Field	Description
`paymentId`	The payment whose status changed.
`paymentStatus`	The new status (see Payment Statuses & FAQ).
`userId` / `orgId`	The user and organization the payment belongs to.
`bankName`	The payer's bank.
`paymentError`	`{ message, type }`, populated when the payment failed.

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.

Updated 7 days ago

Did this page help you?