Authorisation decisions

Unlike notification webhooks, authorisation request webhooks ask you a question and wait for your answer. When a cardholder taps, swipes, or enters their card details, Orenda runs its own checks first — balance, spending limits, merchant category, and country restrictions. If those checks pass, we forward the authorisation to your endpoint. You then have the final say: approve it, or decline it based on your own business rules.

This feature is available by application only. It is not enabled by default — contact the team to request it for your program.

The card network is holding the transaction open while it waits for your answer. Your endpoint has a maximum of 2.5 seconds to respond — if you miss the deadline, the response is ignored and the transaction is treated as unanswered (see failure modes below).

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.

Enabling CARD_AUTHORIZATION_REQUESTED automatically enables both — you will always be consulted on incremental authorisations for transactions you already approved. Both events share the same transaction.transaction_link_id, so you can match an incremental request back to the original authorisation.

Example payload

{
  "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 for it, `retrieval_reference_number`. 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.

Optional fields are omitted when unknown — they will not appear in the payload at all, rather than being sent as null. Do not assume every field is always present.

Refunds

Refunds arrive through the same events — there is no separate refund event. You can tell them apart by the amount: negative for a purchase (money leaving the cardholder), positive for a refund (money coming back).

Be careful with refunds. If your program uses failureMode: "closed" and your endpoint goes down, refunds will be declined too — blocking the cardholder from receiving their money back. To avoid this, always approve requests where amount is positive.

Expected response

Respond with 200 and a JSON body containing a decision field:

Field	Type	Required	Description
`decision`	string	Yes	`"approve"` or `"decline"`
`reason`	string	No	Free text for support and investigation — never shown to the cardholder. Truncated at 200 characters.

Approve:

{ "decision": "approve" }

Decline:

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

`reason` is required on a decline

reason must be one of the values below, and nothing else. It is not a note for our support team — it selects the response code the card network returns, which is what the terminal prints and what the cardholder is told. A decline for an expired card and a decline on your own risk rule should not read the same at the till.

`reason`	What the cardholder sees
`card_expired`	Expired Card
`card_inactive`	Restricted Card
`account_inactive`	Account Restricted
`insufficient_funds`	Insufficient Funds
`limit_exceeded`	Exceeds Withdrawal Amount Limit
`country_blocked`	Country is blocked
`system_error`	Do Not Honour
`mcc_blocked`	Transaction Forbidden to Cardholder
`input_option_blocked`	Transaction Forbidden to Cardholder
`duplicate_request`	Transaction Forbidden to Cardholder
`transaction_forbidden_to_cardholder`	Transaction Forbidden to Cardholder
`unknown`	Transaction Forbidden to Cardholder

Matching ignores case and surrounding whitespace. Nothing else is guessed at: we will not read card-expired or Insufficient Balance as anything but unrecognised.

Your decline is always honoured. An unrecognised or missing reason never turns a decline into an approval and never causes an error — only the code we return changes. Anything outside the list, and an absent reason, is read as unknown and returns 119.That is exactly what every decline returned before this list existed, so a receiver written against the earlier free-text contract keeps working unchanged. It just gives the cardholder the least useful message we have, on every decline. Send a real reason.

system_error is for when you could not decide — your rules engine was down, a dependency timed out. Do not use it to describe the cardholder’s situation. If you would rather we fell back to our own verdict when your side is broken, that is failureMode below, not a reason. We also keep the raw string you sent, for support and investigation: trimmed and truncated at 200 characters. That text is never relayed to the network and never shown to the cardholder — only the code it selects is.

Only 200 with "decision": "approve" approves a transaction. Any other response is treated as no answer — this includes:

Non-200 status codes (3xx, 4xx, 5xx)
Unparseable or empty body
An unrecognised decision value
A timeout
200 {"ok": true} (a common mistake if you reuse a notification webhook handler)

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

Rollout happens in two stages:

Shadow mode (default) — We call your endpoint and record your response, but your decisions have no effect. Transactions are approved or declined based on Orenda’s own checks only. We use this to verify your endpoint responds correctly and within the timeout.
Enforcement — When you are ready, contact the team to enable enforceDecision. From that point, your approve/decline responses directly control whether card transactions go through.

Do not skip shadow mode. If your endpoint returns an unexpected response (e.g. 200 {"ok": true}), enforcement would decline every transaction on your program.

enforceDecision, failureMode, the callback URL, and the timeout are all configured by Orenda — contact the team to set them up.

Verifying the signature

Authorisation request webhooks use a different signature format to notification webhooks. Notification webhooks sign the raw body only. Authorisation requests sign <timestamp>.<body> — you cannot reuse the same verification logic for both.

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();

How to identify an authorisation request

Every delivery includes these headers:

Header	Present on	Purpose
`Orenda-Event-Id`	All webhooks	Deduplicate events
`Orenda-Delivery-Id`	All webhooks	Reference for support investigations
`Orenda-Payload-Signature`	All webhooks	HMAC-SHA256 signature (but the signing base differs — see below)
`Orenda-Signature-Timestamp`	Authorisation requests only	Unix timestamp included in the signing base

If Orenda-Signature-Timestamp is present, this is an authorisation request webhook. You must verify the signature using <timestamp>.<body> as the signing base — not the body alone. If the header is absent, this is a notification webhook and you verify using the body only (see notification webhook signature verification).

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

If the card network does not receive a response in time, it retries the authorisation and we forward it to your endpoint again. You may receive the same authorisation multiple times. Always deduplicate on event_id, which stays the same across retries. Orenda-Delivery-Id changes with each attempt and should not be used for deduplication.

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

Example payload

Fields worth reading twice

Refunds

Expected response

`reason` is required on a decline

What happens when you do not answer

Rolling out safely

Verifying the signature

How to identify an authorisation request

Redeliveries

Other requirements

​Two events

​Example payload

​Fields worth reading twice

​Refunds

​Expected response

​reason is required on a decline

​What happens when you do not answer

​Rolling out safely

​Verifying the signature

​How to identify an authorisation request

​Redeliveries

​Other requirements

Two events

Example payload

Fields worth reading twice

Refunds

Expected response

`reason` is required on a decline

What happens when you do not answer

Rolling out safely

Verifying the signature

How to identify an authorisation request

Redeliveries

Other requirements