Authorisation decisions

Unlike every other webhook in this section, this one asks you a question and waits for the answer. We run our own checks first — balance, spending limits, merchant category, country. If we would approve, we call you. Your answer can turn that approval into a decline.

This is a blocking call on the card network’s clock. Your endpoint must answer within the configured timeout — 2.5 seconds maximum, floored at 50 ms, and 800 ms if the configured value cannot be read. A response that arrives late is a response that did not arrive.

Two events

Event	When
`CARD_AUTHORIZATION_REQUESTED`	The first authorisation on a purchase.
`CARD_AUTHORIZATION_INCREMENTAL`	A later authorisation raising the amount on the same purchase — a fuel pump settling, a hotel extending a stay.

Subscribing to CARD_AUTHORIZATION_REQUESTED subscribes you to both. You cannot be consulted on the first authorisation and silently skipped on the increase; that would mean approving an exposure and never seeing it raised. The two share a transaction.transaction_link_id, so you can tie an increase back to the authorisation you already approved.

What you receive

{
  "event": "card.authorization.requested",
  "event_id": "4bd0e2c3-8780-4344-a8ab-d8c581ce1834",
  "occurred_at": "2026-07-22T22:12:28.000Z",
  "sandbox": false,

  "card": {
    "id": "4781c981-ebd0-42d7-9040-e50b204f91ca",
    "form_factor": "physical",
    "status": "active",
    "last_four": "8707"
  },

  "customer": {
    "id": "b143aab0-c478-4239-af9e-3a2c4bed53b0",
    "name": "Jane Okonkwo"
  },

  "transaction": {
    "id": "4bd0e2c3-8780-4344-a8ab-d8c581ce1834",
    "retrieval_reference_number": "620321283665",
    "transaction_link_id": "156203799486939",
    "type": "Goods and Service",
    "amount": "-120.00",
    "currency": "GBP",
    "billing_amount": "-120.00",
    "billing_currency": "GBP",
    "authentication": {
      "method": "chip",
      "pin": "verified",
      "three_ds": false,
      "sca_applied": false,
      "avs": "not_matched"
    }
  },

  "merchant": {
    "name": "SHELL",
    "city": "Paris",
    "country": "FR",
    "mcc": "5542",
    "mcc_category": "Retail Outlet Services",
    "mcc_description": "Automated Fuel Dispensers"
  }
}

Fields worth reading twice

Field	Notes
`amount` / `billing_amount`	Signed decimal strings in major units. A debit is negative, a credit (refund) positive. Decimal places follow the currency — `-120.00` for GBP, `-12000` for JPY, `-12.000` for BHD. Compare as decimals, not floats.
`currency`	ISO 4217 alpha-3, converted from the network’s numeric code.
`type`	The acquirer’s own service label, passed through verbatim — `"Goods and Service"`, `"Cash Withdrawal (ATM)"`, `"Returns/Refunds"`. Free text: treat an unrecognised value as unrecognised, never as a control.
`event_id`	Stable across redeliveries. Dedupe on it. Currently equal to `transaction.id`; treat them as separate fields, since only `event_id` is contractually stable.
`retrieval_reference_number`	The network’s retrieval reference number, under the provider’s own name — Clowd9 calls it `retrieval_reference_number` and so do we. Use it to reconcile against your copy of the transaction and against anything you get from the scheme. Omitted when the provider sends it blank, so do not assume it is always present on a row you key on it.
`transaction_link_id`	The provider’s own link id. Every authorisation on one purchase shares it — that is how an increase ties back to the authorisation it raises. Omitted when the provider did not send one.
`merchant.mcc`	The network’s merchant category code, exactly as the acquirer sent it — not padded, stripped or trimmed. It is normally four digits including any leading zero (`0742`, not `742`), and that is the form our catalogue and ref-data are keyed on, so it can be looked up as sent. A provider defect can reach you in another shape: we pass it through unchanged, alert on our side, and send no classification with it. Omitted entirely when the provider sends it blank. This is the one to key behaviour on.
`merchant.mcc_category`	The high-level business classification — one of thirteen buckets. A convenience, not a control: we maintain it, so it can change as the classification is revised. Omitted for a code we have not classified — absent means unclassified, not “uncategorised merchant”. A code that does not arrive as four digits is treated as unclassified rather than guessed at, and we raise an alert on our side.
`merchant.mcc_description`	The merchant category’s own name — `"Automated Fuel Dispensers"`. Free text for display, not for keying on: many are ALL-CAPS and the longest runs to 142 characters. Present only alongside `mcc_category`.
`card.id`	Our card identifier — the one our API issued you.
`occurred_at`	ISO 8601 UTC.

transaction.retrieval_reference_number and transaction.transaction_link_id were called transaction.reference and transaction.group_id when this page first went up. They were renamed within a day of publication, before any programme was enabled, so no integration should be affected — but if you built against that first version, they are the same values under the provider’s own names.merchant.mcc was called merchant.category_code. Same rename, same window, same reason — and mcc_category and mcc_description are new alongside it.

Optional fields are omitted when unknown rather than sent as null.

Refunds are included

A refund (Returns/Refunds) is an authorisation too, and you are asked about it on the same events. The payload tells them apart without a separate event name: amount is positive on a credit and negative on a debit, and type carries the acquirer’s label.

This means that under failureMode: "closed", an endpoint that is down declines a refund — the cardholder’s own money coming back — as well as a purchase. If you do not want to screen credits, approve anything with a positive amount.

What you must respond

200 with exactly this shape:

{ "decision": "approve" }

{ "decision": "decline", "reason": "velocity_rule_7" }

reason is optional, free text, and kept for support and investigation. It is never shown to the cardholder, trimmed, and truncated at 200 characters.

Anything else is treated as “no answer.” A 3xx, a 4xx, a 5xx, a body we cannot parse, a decision value we do not recognise, an empty body, or a timeout. There is exactly one way to get an approval: a 200 whose body says "approve".In particular a 200 {"ok": true} — the natural response for a notification receiver — is not an approval.

What happens when you do not answer

Configured per programme as failureMode:

Mode	Behaviour
`closed` (default)	The authorisation is declined. Safest against unscreened spend; while your endpoint is down, your cards stop working.
`open`	We fall back to our own verdict. Our balance, limit, merchant-category and country checks still applied — only your additional check is skipped.

Rolling out safely

Subscribing to the event does not immediately let it decline anything. Enforcement is a separate opt-in (enforceDecision). Until you enable it, your endpoint runs in shadow mode: we call it, record what you said and what we would have answered, and approve on our own verdict. Nothing you return can decline a card. Use that period to confirm your receiver answers the right shape inside the timeout, then turn enforcement on. Going straight to enforcement with a receiver that answers 200 {"ok": true} would decline every card in your programme.

enforceDecision and failureMode have no self-service control yet — ask us and we will set them on your programme’s card policy. Same for the callback URL and timeout.

Verifying the signature

The signing base differs from the other webhooks on this page. Notification webhooks sign the body alone. This one signs <timestamp>.<body>, so a verifier written for the others will reject every one of these.

const crypto = require("crypto");

const sig = req.headers["orenda-payload-signature"];
const timestamp = req.headers["orenda-signature-timestamp"]; // unix seconds

// Reject rather than throw. `Buffer.from(undefined)` throws a TypeError, and
// timingSafeEqual throws a RangeError on a length mismatch — so the naive
// version 500s on an absent or truncated signature, which we read as NO ANSWER
// and, under the default failure mode, decline.
const expected = Buffer.from(
  crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)   // raw body, byte-for-byte
    .digest("hex"),
  "hex"
);
const actual =
  typeof sig === "string" ? Buffer.from(sig, "hex") : Buffer.alloc(0);

const signatureOk =
  actual.length === expected.length &&
  crypto.timingSafeEqual(expected, actual);

// Bind the clock too, or a captured request replays forever.
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
const fresh = Number.isFinite(age) && age < 300;

if (!signatureOk || !fresh) return res.status(401).end();

A delivery can arrive unsigned. If we cannot read your programme’s signing secret we send the request anyway, without Orenda-Payload-Signature or Orenda-Signature-Timestamp — deliberately, because a credential problem on our side must not stop your cards working.Decide which you want and tell us: reject unsigned deliveries (safer, but a credential problem then declines your cards under failureMode: "closed"), or accept them until the secret is in place. Orenda-Event-Id and Orenda-Delivery-Id are always sent, signed or not.

Orenda-Payload-Signature is the same header name the notification webhooks use, with a different signing base. If you serve both families on one URL, tell them apart by the presence of Orenda-Signature-Timestamp — only these decisional deliveries carry it.

Header	Meaning
`Orenda-Payload-Signature`	HMAC-SHA256 hex digest of `<timestamp>.<body>`.
`Orenda-Signature-Timestamp`	Unix seconds. Signed.
`Orenda-Event-Id`	Mirrors `event_id` in the body. The body is authoritative.
`Orenda-Delivery-Id`	This particular delivery. Differs between redeliveries of the same event.

Redeliveries

The card network retries authorisations it does not hear about in time, and we re-run the decision from scratch on each. You will see the same authorisation more than once. event_id is stable across those retries; Orenda-Delivery-Id is not. Dedupe your exposure on event_id, or you will count one purchase twice and decline a customer who is comfortably within their limit.

Other requirements

HTTPS only. Plain HTTP is rejected before the call is made.
Redirects are not followed. A 3xx is treated as no answer — publish the final URL.
Keep the response small. A response over 64 KiB is no answer — we stop reading and, under failureMode: "closed", decline. Answering {"decision":"approve"} followed by 65 KiB of rule context declines the card.
Be quick. Our timeout covers DNS, TLS, your processing and the response body.

Get started

Oversight

Customer operations

Batch payments

Configuration

Two events

What you receive

Fields worth reading twice

Refunds are included

What you must respond

What happens when you do not answer

Rolling out safely

Verifying the signature

Redeliveries

Other requirements

​Two events

​What you receive

​Fields worth reading twice

​Refunds are included

​What you must respond

​What happens when you do not answer

​Rolling out safely

​Verifying the signature

​Redeliveries

​Other requirements

Two events

What you receive

Fields worth reading twice

Refunds are included

What you must respond

What happens when you do not answer

Rolling out safely

Verifying the signature

Redeliveries

Other requirements