> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Set up an endpoint, verify each event, and read the resource it's about

Quidkey sends a signed event to your webhook endpoint when a payment transaction changes state, and when a partner's merchant goes live, is suspended or is reinstated. Each event is a document in the API's own [format](https://docs.quidkey.com/api-v1/standards/responses.md): `result` is the event, and its `subject` links to the resource it's about. An event tells you what happened. Read its subject to see where it stands.

The same body also carries the fields of the [earlier event format](#the-earlier-format), which integrations built on it read. A new integration reads `result` and can ignore them.

## Set Up an Endpoint

A partner has one endpoint, and receives every event for the payment transactions it creates and its merchants' status changes:

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/partners/p_1/webhook-endpoints' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "6f1d7a52-0f3c-4c8e-9a51-2a7d5b8c9e10"' \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://api.example.com/webhooks/quidkey" }'
```

A merchant can have several named endpoints:

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/webhook-endpoints' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "0b8e3f4a-3c5d-4f7e-8a9b-1c2d3e4f5a6b"' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "orders", "url": "https://api.example.com/webhooks/quidkey" }'
```

The response holds the endpoint, with its `signing_secret`:

```json Response theme={null}
{
  "result": {
    "_type": "webhook_endpoint",
    "_uri": "/webhook-endpoints/we_1",
    "_view": "full",
    "id": "we_1",
    "owner": { "_link": "/merchants/m_1", "_type": "merchant", "id": "m_1" },
    "name": "orders",
    "url": "https://api.example.com/webhooks/quidkey",
    "is_signed": true,
    "status": "active",
    "is_default": false,
    "signing_secret": "whsec_YOUR_SIGNING_SECRET",
    "created_at": "2026-11-02T10:00:00.000Z",
    "updated_at": "2026-11-02T10:00:00.000Z"
  },
  "entities": {},
  "not_included": []
}
```

> [!WARNING]
>
> `signing_secret` appears only in this response. Store it straight away in a secret store. A retry with the same `Idempotency-Key` answers the endpoint without it, and so can the answer to a create you sent once, when Quidkey sent it on again after a dropped connection. If an answer has no `signing_secret`, `POST /webhook-endpoints/{id}:rotateSecret` issues a new one, and replaces the old one at once, with no overlap.

* `url` is an absolute HTTPS URL on a public address. Treat it as a secret if it carries a token.
* An endpoint created through the API receives events for test payment transactions as well as live ones.
* `PATCH /webhook-endpoints/{id}` changes `url` and `status`, and on a merchant's endpoint `is_signed` and `is_default`. An `inactive` endpoint receives nothing.

### Where a Payment Transaction's Events Go

The first of these that applies:

1. A payment transaction created with a **partner's credential**, while its merchant is still with that partner, reports to the partner's endpoint. If the partner has no endpoint, its events go nowhere: they never go to the merchant's destinations instead.
2. A payment transaction that named endpoints in `webhook_endpoints`, up to 10, reports to each of them that takes its environment, each delivery signed with that endpoint's secret. If none of them takes its environment, its events go nowhere.
3. A merchant with a webhook URL of its own, shown as **Default webhook** under **Developers** in the [Console](https://console.quidkey.com), gets its events there, live and test alike, with [one more earlier field](#the-default-webhook). The merchant can remove it in the Console, and this API has no operation that sets one.
4. The merchant's default endpoint, set with `is_default: true`, if it's `active` and takes the payment transaction's environment.
5. The merchant's one `active` endpoint that takes the payment transaction's environment, if there's exactly one.

Otherwise the event goes nowhere. A merchant with more than one active endpoint sets a default, or names one on each payment transaction. A reversal's events go where its payment transaction's did.

An endpoint created through the API takes both environments: live and test payment transactions. An endpoint registered outside the API can take only live or only test ones, and then rules 2, 4 and 5 pass over it for a payment transaction of the other kind. An `inactive` endpoint receives nothing, even where rule 1 or 2 names it.

## The Event

A payment transaction's event:

```json theme={null}
{
  "result": {
    "_type": "event",
    "id": "evt_0192f0c1-7a3b-7cde-9f01-23456789abcd",
    "type": "transaction.payment.completed",
    "created_at": "2026-11-10T10:00:00.000Z",
    "subject": { "_link": "/transactions/tx_1", "_type": "transaction", "id": "tx_1" }
  },
  "entities": {},
  "not_included": []
}
```

The body also holds the earlier format's `id`, `object`, `created`, `type` and `data`, left out here.

| Field | Meaning |
| - | - |
| `result._type` | Always `event`. |
| `result.id` | The event's ID. Every delivery of one event carries the same `id`, a resend included, and no two events share one. **De-duplicate on it.** |
| `result.type` | What happened: the subject's type and status, as reading the subject answered them when the event was raised. See [The Events](#the-events). |
| `result.created_at` | When the event was raised, to the millisecond. |
| `result.subject` | A link to the resource the event is about. Read it for where it stands now at the path its `id` gives, `/transactions/{id}` or `/merchants/{id}`. Don't send your access token to a URL taken from an event's body. |
| `entities` | Always `{}`. An event doesn't include its subject. |
| `not_included` | Always `[]`. |

An event has no `_uri`: no operation reads an event. The API reference documents each event's body under **Events**.

## The Events

| `result.type` | Sent when | `subject` |
| - | - | - |
| `transaction.payment.processing` | The customer's bank accepted a payment transaction through a virtual account, and its money is on its way. No event follows when it completes. | The payment transaction |
| `transaction.payment.completed` | The customer's bank accepted a direct payment transaction, and the provider reported it finished. | The payment transaction |
| `transaction.payment.failed` | The payment transaction failed, and nothing further will happen to it. | The payment transaction |
| `transaction.payment.cancelled` | The customer or Quidkey cancelled the payment transaction before it moved money. That includes the customer declining or cancelling its payment agreement, such as a PayTo agreement, in their banking app or through Quidkey. | The payment transaction |
| `transaction.payment.unresolved` | The payment transaction ended in an error after reaching its provider, so its outcome isn't known. | The payment transaction |
| `transaction.reversal.completed` | The customer's bank took a payment transaction back. | The reversal |
| `transaction.reversal.failed` | Quidkey corrected a reversal's status to `failed`. | The reversal |
| `transaction.reversal.cancelled` | Quidkey corrected a reversal's status to `cancelled`. | The reversal |
| `merchant.pending` | Quidkey reinstated a merchant that hadn't gone live. | The merchant |
| `merchant.active` | A merchant went live, or Quidkey reinstated one that had. | The merchant |
| `merchant.suspended` | Quidkey suspended a merchant, or changed a suspended merchant's status, as activating it does. | The merchant |

A transaction's event type is `transaction.<type>.<status>` and a merchant's is `merchant.<status>`, with `type` and `status` as `GET /transactions/{id}` and `GET /merchants/{id}` answer them. A merchant's events go to the partner's endpoint only, while the merchant is still with that partner. **Branch on `result.type`.** More types can appear: answer one you don't recognise with a `2xx` and ignore it. A body with no `result` reports a state no event type covers, which Quidkey sends in the earlier format alone: answer it with a `2xx` too.

A reversal's subject is the reversal, whose `parent_transaction` is the payment transaction. See [Handle a reversal](https://docs.quidkey.com/api-v1/journeys/reversals.md).

On `transaction.payment.unresolved`, don't take payment again for that order until it resolves: `transaction.payment.processing` or `transaction.payment.completed` can still follow, or `transaction.payment.failed` once Quidkey confirms.

These send no event, so poll for them:

| What | Poll |
| - | - |
| Refunds | `GET /transactions/{refund_id}` |
| Payment transactions through a payment link | `GET /merchants/{id}/transactions?payment_link_id={id}` |
| Payouts | `GET /merchants/{id}/payouts` |
| Onboarding, identity checks and capabilities | `GET /merchants/{id}/onboarding` |

### When a Payment Transaction Has Succeeded

Each payment transaction sends one of two events when the customer's bank accepts it, depending on how its money is routed.

| You see | It means | What to do |
| - | - | - |
| `transaction.payment.processing` | The customer's bank accepted a payment transaction through a virtual account. The money hasn't landed. | Fulfil the order. The bank can still take the payment transaction back later, which sends `transaction.reversal.completed`. |
| `transaction.payment.completed` | The customer's bank accepted a direct payment transaction, and the provider reported it finished, which can be days before the money arrives. | Fulfil the order. The bank can still take it back, as above. |
| `GET /transactions/{id}` reads `completed` after `transaction.payment.processing` | The merchant's payout of the payment transaction finished. No event is sent for it. | Nothing. A payout lists it once it's paid out to the merchant. |
| `transaction.reversal.completed`, later | The bank took the money back. | See [Handle a reversal](https://docs.quidkey.com/api-v1/journeys/reversals.md). |

No status, `completed` included, confirms that money has reached an account. Reconcile money in hand with [payouts](https://docs.quidkey.com/api-v1/journeys/reconcile.md).

### Failure Reasons

The payment transaction a `transaction.payment.failed` event names carries `failure`, which says why it failed: `code`, `message`, written for your customer, and `retryable`, whether the same payment transaction could succeed if tried again, or `null` when neither the bank nor Quidkey gave an indication. Quidkey doesn't retry a failed payment transaction: whether to ask the customer to pay again is yours to decide.

| `code` | Meaning |
| - | - |
| `INSUFFICIENT_FUNDS` | The customer's bank declined the payment transaction because the account didn't hold enough funds. |
| `ACCOUNT_CLOSED` | The customer's bank declined the payment transaction because the account is closed. |
| `ACCOUNT_BLOCKED` | The customer's bank declined the payment transaction because the account can't be debited. |
| `AGREEMENT_INACTIVE` | The payment transaction couldn't go ahead because the customer's payment agreement, such as a PayTo agreement, wasn't approved or is no longer active. A customer declining or cancelling the agreement themselves is a cancellation instead, which sends `transaction.payment.cancelled`. |
| `DECLINED` | The customer's bank declined the payment transaction without a more specific reason. |
| `UNKNOWN` | No reason the customer can act on was reported. |

Treat `code` as an open set: handle a code you don't recognise as you would `UNKNOWN`. When the bank reports a reason after the event, the payment transaction's `code` becomes more specific, such as `UNKNOWN` becoming `DECLINED`, and no event is sent for that, so read the reason on the payment transaction.

## Verify Every Event

Every delivery is signed, unless a merchant registered the endpoint with `is_signed: false`. A partner's endpoint is always signed. **Verify the signature before you parse the body.**

Each delivery is a `POST` with these headers:

| Header | Meaning |
| - | - |
| `Content-Type` | `application/json` |
| `X-Signature` | `t=TIMESTAMP,v1=SIGNATURE`. Absent on an endpoint registered with `is_signed: false`. |
| `X-Timestamp` | The `t` value, in Unix seconds |
| `X-Client-Id` | On a transaction's event, the `client_id` of the merchant the payment transaction is for, on a partner's endpoint too. On a merchant's event, the partner's `client_id`. |

`SIGNATURE` is a hex HMAC-SHA256 of the timestamp, a full stop and the raw request body, keyed by the endpoint's full `signing_secret`, `whsec_` prefix included. It covers the whole body, `result` and the earlier fields alike.

* Verify against the raw body bytes, exactly as received. Capture them before any JSON parser runs.
* Refuse a timestamp more than 5 minutes old.
* Compare signatures in constant time.
* On a signed endpoint, refuse a delivery that has no `X-Signature`.

> [tab] Node.js
>
> ```javascript theme={null}
> import crypto from 'crypto';
>
> const TOLERANCE_SECONDS = 300;
>
> function verifyQuidkeySignature(rawBody, signatureHeader, secret) {
>   const match = signatureHeader?.match(/^t=(\d+),v1=([a-f0-9]+)$/);
>   if (!match) throw new Error('Malformed signature header');
>   const [, timestamp, signature] = match;
>
>   if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) {
>     throw new Error('Timestamp outside tolerance');
>   }
>
>   const expected = crypto
>     .createHmac('sha256', secret) // the full "whsec_..." secret
>     .update(`${timestamp}.${rawBody}`)
>     .digest('hex');
>
>   const a = Buffer.from(expected);
>   const b = Buffer.from(signature);
>   if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
>     throw new Error('Signature mismatch');
>   }
> }
> ```

> [tab] Python
>
> ```python theme={null}
> import hashlib
> import hmac
> import time
>
> TOLERANCE_SECONDS = 300
>
> def verify_quidkey_signature(raw_body: bytes, signature_header: str | None, secret: str) -> None:
>     if not signature_header:
>         raise ValueError('Missing signature header')
>     parts = dict(p.split('=', 1) for p in signature_header.split(',') if '=' in p)
>     timestamp, signature = parts.get('t'), parts.get('v1')
>     if not timestamp or not timestamp.isdigit() or not signature:
>         raise ValueError('Malformed signature header')
>
>     if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
>         raise ValueError('Timestamp outside tolerance')
>
>     # Keyed by the full "whsec_..." secret
>     signed_payload = f"{timestamp}.".encode() + raw_body
>     expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
>
>     if not hmac.compare_digest(expected, signature):
>         raise ValueError('Signature mismatch')
> ```

> [tab] Stripe SDK (Node.js)
>
> ```javascript theme={null}
> import express from 'express';
> import Stripe from 'stripe';
>
> const stripe = new Stripe(process.env.STRIPE_API_KEY);
> const app = express();
>
> app.post('/webhooks/quidkey', express.raw({ type: 'application/json' }), (req, res) => {
>   let event;
>   try {
>     event = stripe.webhooks.constructEvent(
>       req.body, // the raw Buffer
>       req.get('x-signature'),
>       process.env.QUIDKEY_SIGNING_SECRET // the full "whsec_..." secret
>     );
>   } catch (err) {
>     return res.status(400).send('Invalid signature');
>   }
>   handleEvent(event);
>   res.status(200).send('OK');
> });
> ```

## Delivery

* **Each event is delivered once.** It isn't retried automatically, and some activity sends no event, so poll the API for what you must see.
* **Order isn't guaranteed.** Read the subject if order matters.
* **Answer fast.** Return a `2xx` quickly, and do the work afterwards.
* **De-duplicate on `result.id`.** A resend Quidkey makes carries the same `result.id` as the delivery it repeats, and every event of a payment transaction has its own.
* **Handle each state once.** Quidkey can send a new event, with a new `result.id`, for a state you've already handled, as when Quidkey staff send a payment transaction's state again. So make what you do for a subject's state idempotent, such as fulfilling an order only once, as well as de-duplicating on `result.id`.

When the customer's bank accepts a payment transaction, you receive `transaction.payment.completed` if it's direct, or `transaction.payment.processing` if it goes through a virtual account. Both mean the same thing for your order: fulfil it. Handle the two together.

Read the subject first, and decide from what the read answers, not from the event alone: the read is the subject as it stands. Then record the event's `result.id` before you do the work, in a table where it's unique, in the same database transaction as the work: a second delivery of the event then records nothing and does nothing, and work that fails leaves the event unrecorded. Read the subject before that transaction opens, so it holds no database connection while it waits on the API.

```javascript theme={null}
async function handleEvent(event) {
  const { id, type, subject } = event.result;

  switch (type) {
    // The bank accepted the payment transaction: `processing` through a virtual account,
    // `completed` when it's direct. Either way, fulfil the order, once.
    case 'transaction.payment.processing':
    case 'transaction.payment.completed': {
      const payment = await quidkey.get(`/transactions/${encodeURIComponent(subject.id)}`);
      if (!['processing', 'completed'].includes(payment.result.status)) return;
      return once(id, tx => fulfilOrderOnce(tx, payment.result.order.order_id, payment.result));
    }
    case 'transaction.reversal.completed': {
      const reversal = await quidkey.get(`/transactions/${encodeURIComponent(subject.id)}`);
      return once(id, tx =>
        recordReversalOnce(tx, reversal.result.parent_transaction.id, reversal.result)
      );
    }
    case 'merchant.pending':
    case 'merchant.active':
    case 'merchant.suspended': {
      const merchant = await quidkey.get(`/merchants/${encodeURIComponent(subject.id)}`);
      return once(id, tx => refreshMerchant(tx, merchant.result));
    }
  }
}

// Does `work` unless this event was already handled. `event_id` is the table's primary key, so a
// second delivery inserts nothing.
function once(eventId, work) {
  return db.transaction(async tx => {
    const recorded = await tx.query(
      'INSERT INTO quidkey_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING',
      [eventId]
    );
    if (recorded.rowCount === 0) return;
    await work(tx);
  });
}
```

`quidkey.get` stands for your own HTTP client, sending your access token, with `https://api.quidkey.com/v1` as its base URL. It reads the subject at a path built from its `id`, never at a URL taken from the body. `db` stands for your database.

## The Earlier Format

Every event also carries the fields of the event format integrations built before this one read: `id`, `object`, `created`, `type` and `data`, beside `result`, `entities` and `not_included`. The names don't overlap, so a parser written for either format reads its own fields. They're described here for those integrations, and the API reference marks them deprecated. Their amounts, statuses and field names are their own, not the API's.

A payment transaction's event, in the earlier format, to a merchant's endpoint:

```json theme={null}
{
  "id": "evt_3c6f1a9e-2b7d-4e58-9f0a-8d4c2e6b1f73",
  "object": "event",
  "created": 1793438400,
  "type": "quidkey.payment_request.succeeded",
  "data": {
    "object": {
      "id": "tx_1",
      "amount": "4500",
      "currency": "GBP",
      "status": "received",
      "test": false,
      "sandbox": false,
      "metadata": {
        "order_id": "ORD-123",
        "payment_token": "ptok_YOUR_PAYMENT_TOKEN"
      },
      "fees": {
        "total_fees": "68",
        "fees_currency": "GBP",
        "fees_breakdown": [
          {
            "id": "fee_1",
            "type": "percentage",
            "amount": "68",
            "tax_amount": "0",
            "currency": "GBP",
            "rate_type": "domestic_percent_fee",
            "rate_value": "1.5",
            "notes": "1.5% fee on 45 GBP"
          }
        ]
      },
      "rewards": {
        "extra_rewards": 150,
        "total_rewards": 300,
        "description": "Points for paying by bank"
      }
    }
  }
}
```

| Field | Meaning |
| - | - |
| `id` | On a payment transaction's event, shared by every event of that transaction, and a reversal's events share their own, so an integration on this format de-duplicates on `id` and `type` together. On `quidkey.merchant.status_changed`, unique to the event, and the same as `result.id`. It names no resource: read the transaction at `data.object.id`. |
| `object` | Always `event`. |
| `created` | `result.created_at`, in Unix seconds. |
| `type` | The event type in the earlier format. |
| `data.object` | What the event is about. |

### Earlier Event Types

| `type` | Sent when | `result.type` | `data.object.status` |
| - | - | - | - |
| `quidkey.payment_request.pending` | A payment transaction's outcome isn't known, and to a merchant also one that ended in an error, which can still settle. | `transaction.payment.unresolved`, and to a merchant also `transaction.payment.failed` for an error before the payment transaction reached its provider | `unknown`, and to a merchant also `error` |
| `quidkey.payment_request.succeeded` | The customer's bank accepted the payment transaction. | `transaction.payment.processing` or `transaction.payment.completed` | `received`, `fee_paid`, `converted` or `completed` |
| `quidkey.payment_request.failed` | The payment transaction failed, and to a partner's endpoint also ended in an error, which can still settle: see `unresolved` below. | `transaction.payment.failed`, and to a partner also `transaction.payment.unresolved` | `failed`, and to a partner's endpoint also `error` |
| `quidkey.payment_request.canceled` | The payment transaction was cancelled, including by the customer declining or cancelling its payment agreement. **One `l`.** | `transaction.payment.cancelled` | `cancelled` |
| `quidkey.payment_request.reversed` | Any event of a reversal. | `transaction.reversal.completed`, `.failed` or `.cancelled` | The reversal's status |
| `quidkey.merchant.status_changed` | A merchant went live, was suspended or was reinstated. To the partner's endpoint only, while the merchant is still with that partner. | `merchant.pending`, `merchant.active` or `merchant.suspended` | None: it carries `activation_status` and `suspended` |

"To a merchant" means to a merchant's endpoint and to its Default webhook. Payment transaction event types are named `quidkey.payment_request.*`.

A payment transaction's event carries these in `data.object`:

| Field | Meaning |
| - | - |
| `id` | The transaction's ID, as `result.subject.id`. On `.reversed` it's the reversal's ID, whose `parent_transaction` is the payment transaction. A refund is created on the payment transaction's ID. |
| `amount` | A string of minor units, `"4500"` for GBP 45.00, not a `Money` object. On `.reversed`, the reversal's amount. |
| `currency` | The currency of `amount`. |
| `status` | The transaction's status in the earlier format's own vocabulary, which [Earlier Event Types](#earlier-event-types) maps to each type. It isn't the API's `status`. |
| `test` | `true` for a test payment transaction, and for a reversal of one. |
| `sandbox` | The same as `test`. |
| `metadata.order_id` | The `order.order_id` you sent, or `null`. |
| `metadata.payment_token` | The checkout handle that integrations on the previous API correlate on, or `null`, as on a reversal. |
| `fees` | What Quidkey charged, once the transaction has succeeded and Quidkey holds its fees, as on `succeeded`. Absent otherwise. |
| `rewards` | The rewards the payment transaction was created with, once it has succeeded. Absent on one created with none. |
| `failure` | Why the payment transaction failed, on `failed` and only there. See [Earlier Failure Reasons](#earlier-failure-reasons). |
| `payer` | Only to a partner's endpoint, on every event. Who paid, or `null` until an identified customer has authorized the payment transaction, and on one no identified customer authorized. |
| `unresolved` | Only to a partner's endpoint, on every event. `true` on a `failed` event when the payment transaction ended in an error after reaching its provider and may still complete: a later `succeeded` can follow, so don't take payment again for that order until it resolves. `false` otherwise. |

`fees`:

| Field | Meaning |
| - | - |
| `total_fees` | The fees, a string of minor units. |
| `fees_currency` | The currency of the fees. |
| `fees_breakdown` | One entry per fee. |
| `fees_breakdown[].id` | The fee's ID. |
| `fees_breakdown[].type` | `percentage` or `fixed`. |
| `fees_breakdown[].amount` | The whole fee taken, a string of minor units, including any tax charged on top of it. |
| `fees_breakdown[].tax_amount` | The tax charged on top of the fee and included in `amount`, a string of minor units: `"0"` when no tax applies. |
| `fees_breakdown[].currency` | The currency of `amount`. |
| `fees_breakdown[].rate_type` | Quidkey's name for the rate the fee comes from, such as `domestic_percent_fee`. |
| `fees_breakdown[].rate_value` | A decimal string: on a `percentage` fee the percentage, `"1.5"` for 1.5%, and on a `fixed` fee the amount in major units. |
| `fees_breakdown[].notes` | The fee described for people, or `null`. |

`rewards`:

| Field | Meaning |
| - | - |
| `extra_rewards` | The points for this payment transaction, as a number. The API writes points as a [decimal string](https://docs.quidkey.com/api-v1/standards/responses.md#points) instead. |
| `total_rewards` | The customer's total points, as a number. Absent when none was given. |
| `description` | The text shown beside the points, or `null`. |

`payer`, when it isn't `null`:

| Field | Meaning |
| - | - |
| `id` | The partner's own handle for the payer, `pyr_…`. The same person under another partner has another. |
| `releasable`, `releasable_max_amount` | Whether the payer's standing PayTo agreement could be reused for a new payment transaction at the partner's shops, and the most one such payment transaction may take, in minor units, or `null`. The v1 API has no operation that reuses an agreement, so a v1 integration can ignore them. |
| `authority.type` | What the payment transaction was authorized under: `payto_agreement` or `saved_account`. |

`quidkey.merchant.status_changed` carries these in `data.object`:

| Field | Meaning |
| - | - |
| `merchant_id` | The merchant's ID, as `result.subject.id`. |
| `activation_status` | `active` once the merchant has gone live, otherwise `inactive`. |
| `suspended` | Whether Quidkey has suspended the merchant. |
| `changed_at` | When the status changed, RFC 3339. |

### Earlier Failure Reasons

Every earlier-format `failed` event carries `data.object.failure`, with `code`, `message` and `retryable` as the payment transaction's [`failure`](#failure-reasons) holds them. Its codes are the payment transaction's in lower case: `INSUFFICIENT_FUNDS` on the payment transaction is `insufficient_funds` in `data.object.failure`, and `UNKNOWN` is `unknown`. Other earlier-format events don't carry it.

### The Default Webhook

A merchant's **Default webhook**, rule 3 in [Where a payment transaction's events go](#where-a-payment-transactions-events-go), gets the same events as a merchant's endpoint, and reads the earlier format as a merchant does. Its `data.object.metadata` carries one more field:

| Field | Meaning |
| - | - |
| `metadata.bank_name` | The name of the customer's bank, or `null` where Quidkey doesn't hold it. |

It never carries `payer` or `unresolved`. It's always signed, with the Default webhook's own `whsec_` secret, in the same way as an endpoint's delivery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.