# Webhooks

> Receive signed events from Payments AI — setup, HMAC verification, and event payloads.

A webhook is an HTTPS `POST` that Payments AI sends to **your** server when something happens in your merchant account — a payment completes, a subscription starts, a dispute opens. You register a public URL and subscribe to event types. We send a signed JSON payload each time one of those events occurs.

## What a request looks like

Each delivery is one `POST`:

```http
POST /webhooks/payments-ai HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: 1786381404
X-Webhook-Id: 0193a1b2-c3d4-7e5f-8000-0000000000ef
X-Webhook-Event: payment.completed
X-Webhook-Signature: sha256=a1b2c3d4e5f6...
```

`X-Webhook-Id` identifies the event. It stays the same on every retry and resend of that event, so use it to drop duplicates.

Every event body carries three top-level fields next to the event's own fields. There is no `type`, `id`, or `data` envelope.

| Field        | Value                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `eventId`    | The event id. Equal to `X-Webhook-Id`, and the same on every retry and resend of the event.                         |
| `eventType`  | The event type, for example `payment.completed`. Equal to `X-Webhook-Event`.                                        |
| `merchantId` | The merchant the event belongs to. For a sub-merchant event sent to a parent endpoint, this is the sub-merchant id. |

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000ef",
  "eventType": "payment.completed",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "transactionId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3b",
  "amount": 42.5,
  "currency": "usd",
  "occurredAt": "2026-08-10T17:03:24.291Z"
}
```

The signature covers the body, so `eventId` and `eventType` are signed. The `X-Webhook-Id` and `X-Webhook-Event` headers are not, so prefer the body fields once the signature checks out. Do not rely on key order.

The test ping is the exception — it has `type` and `createdAt` only. See [Test your endpoint](#test-your-endpoint).

Payloads contain ids, amounts, and emails. They never include raw card data.

## Create a destination

1. Sign in to the [Payments AI dashboard](https://mor.payments.ai).
2. Open **Developer Tools → Webhooks**.
3. Enter a public HTTPS URL, select the events you want, and optionally add custom headers.
4. Copy the HMAC signing secret from the modal after create. Store it as `PAI_WEBHOOK_SECRET`.

Creating, deleting, testing, and resetting the circuit require **Owner or Admin**. Any team member with merchant access can view destinations.

Register the destination on the same sandbox or live deployment where you want events.

The URL must be HTTPS and resolve to a public address. `localhost` and private networks are rejected. See [Webhook URL forbidden](/errors/webhook-destination-url-forbidden).

### Parent merchants and sub-merchants

If you created sub-merchants from your **parent** merchant, you can also receive webhooks for activity on those sub-merchants on **your** endpoints — without configuring a URL on every sub-merchant.

1. On the **parent** merchant, open **Developer Tools → Webhooks**.
2. When you add an endpoint, enable **Receive sub-merchant events**. You can also turn this on later from the Webhooks table.
3. Subscribe to the event types you still want on that endpoint.

This is **opt-in per endpoint**. We only send a sub-merchant event when the endpoint is subscribed to that type. Each JSON body includes **`merchantId`** for the merchant where the activity happened, so you can tell sub-merchants apart. Signing still uses that endpoint’s HMAC secret.

Sub-merchant dashboards do not show this option; set it on the parent merchant.

## Verify and handle events

Always verify the signature on the **raw request body** before you parse JSON. Re-serializing the body after `JSON.parse` changes the bytes and the check fails.

We sign `{timestamp}.{rawBody}` with HMAC-SHA256. The secret is the 64-character hex value from destination create. The `X-Webhook-Signature` header is `sha256=` plus the lowercase hex digest. Compare with a constant-time function.

<CodeExampleTabs
  examples={[
    {
      label: 'Node',
      language: 'ts',
      code: buildNodeWebhookVerifySnippet(),
    },
    {
      label: 'Python',
      language: 'py',
      code: buildPythonWebhookVerifySnippet(),
    },
  ]}
/>

Read `X-Webhook-Timestamp` and `X-Webhook-Signature` from the request headers. You may reject timestamps that are too far from now (for example five minutes) to limit replay; we do not enforce that window on our side.

**Respond with 2xx quickly.** Verify, enqueue your work, and return. Heavy fulfillment should run in a background job.

If one URL receives several event types, branch on `eventType` in the verified body (the `X-Webhook-Event` header carries the same value). Do not guess the type from field shape: `payment.completed` and `payment.refunded` share most fields, and payment events may carry `subscriptionId` or `customerId` too. Subscribe only the events you need.

Custom headers you configured are sent on every delivery. We then set `Content-Type`, `X-Webhook-Timestamp`, `X-Webhook-Id`, `X-Webhook-Event`, and `X-Webhook-Signature`. A custom `Content-Type` is overwritten. The test ping has no `X-Webhook-Id`.

## Test your endpoint

- In **Developer Tools → Webhooks**, choose **Test Connection** (Owner or Admin) to send a signed ping. It does **not** write delivery history and does **not** trip the circuit breaker.

```json
{
  "type": "webhook.test",
  "createdAt": "2026-08-27T12:00:00.000Z"
}
```

- **Notification Center** lists deliveries for real events (request outcome, status).
- For local development, expose a public HTTPS URL with [ngrok](https://ngrok.com) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/). We reject `localhost`.

Test ping timeout is **15 seconds**. Live delivery timeout is **10 seconds**.

## Delivery

- Success is any **2xx** within **10 seconds**. Timeouts, non-2xx, and network errors are failed attempts.
- Live delivery does **not** follow redirects (`redirect: error`).
- Delivery is **at least once**. The same event can reach you more than once, so dedupe on `eventId` (equal to `X-Webhook-Id`).

### Retries

- Each event gets up to **3 automatic attempts** per endpoint. After a failed attempt we retry **1 minute** later, and after a second failure **15 minutes** later.
- Every attempt is its own row in Notification Center, so you can see each response.
- When the last automatic attempt fails, we email the merchant owner.
- If you remove an event type from the endpoint, or turn off **Receive sub-merchant events**, scheduled retries and paused deliveries it no longer receives are cancelled instead of sent.

### Circuit breaker

- After **5 consecutive** 5xx or network failures, the endpoint's **circuit opens** and we email the merchant owner. **4xx does not** count toward the circuit.
- While the circuit is open, new events are recorded as **Paused** and scheduled retries wait. A paused delivery does not use an attempt until it is sent.
- Every **5 minutes** we send one waiting delivery as a probe. A **2xx** closes the circuit; any other result keeps it open for another 5 minutes. A probe that gets a 5xx or network error goes back to **Paused** and does not use an attempt; a 4xx counts as one.
- Retries that are already due go out first, then paused deliveries, roughly in the order they were recorded. New events are sent as soon as they happen, so delivery order across events is not guaranteed.
- To close the circuit at once, choose **Reset circuit** in **Developer Tools → Webhooks** (Owner or Admin). Waiting deliveries start going out within about 15 seconds.
- To see what is waiting, filter Notification Center by **Paused**.

### Resend

- In Notification Center, **Resend** (Owner or Admin) sends a delivery again as a new manual attempt, even while the circuit is open. A 2xx closes the circuit.
- Resend also cancels that event's scheduled retries and paused delivery for the same endpoint.
- A delivery shown as **Pending** is still being sent, and resend is refused for it. If it has been **Pending** for **15 minutes** or more, the attempt was lost: resend is allowed and marks the stuck delivery as failed.

If deliveries stop, see [Getting help](/getting-help) and confirm the URL is still public ([Webhook URL forbidden](/errors/webhook-destination-url-forbidden)).

## Event catalog

Amounts are JSON **numbers in major units** (for example `42.5`), not cents. Currency is typically a lowercase ISO code.

The primary id field on every event is a **Payments AI id** — the same id you'd see in the dashboard or the Merchant Public API. Where the underlying record originated from an upstream provider, that provider's reference id is also included as a separate `external*` field for reconciliation. Treat the Payments AI id as the one to key your system on; the `external*` field is optional.

Every event below also carries `eventId`, `eventType`, and `merchantId` (see [What a request looks like](#what-a-request-looks-like)). The payload columns list the event's own fields.

There are **no invoice** webhooks.

### Payments

| Event               | When it fires     | Payload                                                                                                                                                                                                                                           |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.completed` | Payment succeeds  | `transactionId` (Payments AI id), `externalTransactionId`, `amount`, `currency`, `occurredAt`, `orderId` (nullable), `customerId` (nullable), `subscriptionId` (nullable), `metadata`, plus [buyer billing details](#buyer-billing-details)       |
| `payment.failed`    | Payment fails     | `transactionId` (Payments AI id), `externalTransactionId`, `occurredAt`, `orderId` (nullable), `customerId` (nullable), `subscriptionId` (nullable), `metadata`, `declineReason` (nullable), plus [buyer billing details](#buyer-billing-details) |
| `payment.refunded`  | A refund succeeds | `refundId` (Payments AI id) plus the `payment.completed` fields without the buyer billing details. `amount` is the amount refunded by **this** refund, so each partial refund sends its own event once. `transactionId` is the refunded payment.  |

Tell `payment.completed` and `payment.refunded` apart by `eventType`.

`declineReason` is sent on `payment.failed` only: `insufficient_funds`, `expired_card` or `card_declined` when the card was declined, or `null` when the payment provider gave no decline code.

`orderId`, `customerId`, and `subscriptionId` are JSON `null` when Payments AI cannot resolve a link (for example plan-only checkouts without an order, or a payment that arrives before the membership webhook creates the subscription row). `subscriptionId` is also `null` for a one-time or free-access purchase: it is no subscription, so it never sent `subscription.created`.

`metadata` is the object you sent when you [created the order](/multi-item-checkout#create-an-order), with its keys and values exactly as sent. It is read from the order named by `orderId`, so renewals and the first charge after a trial carry it too. It is `{}` when the order has no metadata or `orderId` is `null`.

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000ef",
  "eventType": "payment.completed",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "transactionId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3b",
  "externalTransactionId": "pay_XXXXXXXX",
  "amount": 42.5,
  "currency": "usd",
  "occurredAt": "2026-08-10T17:03:24.291Z",
  "orderId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3c",
  "metadata": { "cart_order_number": "SO-10482" },
  "customerId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3d",
  "subscriptionId": null,
  "billingName": "Dana Buyer",
  "billingAddress": {
    "line1": "10 Downing Street",
    "line2": "Flat 2",
    "city": "London",
    "postalCode": "SW1A 2AA",
    "country": "GB"
  },
  "phone": null
}
```

`payment.refunded` has the `payment.completed` shape without the buyer billing details, plus `refundId`. It is the `id` of the refund in `refunds` on [`GET .../transactions/{id}`](/public-api#refunds-on-a-transaction). It is sent for each refund the payment provider reports, including refunds made outside Payments AI, and only once per refund even when the provider reports the same refund again.

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f0",
  "eventType": "payment.refunded",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "refundId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3e",
  "transactionId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3b",
  "externalTransactionId": "pay_XXXXXXXX",
  "amount": 5,
  "currency": "usd",
  "occurredAt": "2026-08-12T09:15:02.104Z",
  "orderId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3c",
  "metadata": { "cart_order_number": "SO-10482" },
  "customerId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3d",
  "subscriptionId": null
}
```

#### Buyer billing details

`payment.completed`, `payment.failed`, and `customer.created` carry the buyer's billing details at top level. **These events contain buyer personal data (PII)**: store and log them as personal data, and do not forward them to systems that should not hold it.

| Field            | Type             | Value                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `billingName`    | string or `null` | The name on the payment's billing address. `null` when the payment carries none.                                                                                                                                                                                                                                                                                             |
| `billingAddress` | object or `null` | The payment's billing address with `line1`, `line2`, `city`, `state`, `postalCode`, and `country`. Blank lines are left out. An address missing `line1`, `city`, or `postalCode` is cut down to `{ "country": "GB" }`, or `null` when it has no country, so `{ "country": ... }` does not mean the buyer gave no street address. `null` when the payment carries no address. |
| `phone`          | string or `null` | The phone stored on the customer. When it has none, the phone from the buyer's successful payment or active membership is stored, so a phone the merchant set in the dashboard or API is never replaced. A failed attempt's phone is not stored, but its `payment.failed` carries the phone entered at checkout when the customer has none. `null` when there is no phone.   |

All three are `null` on events created after a customer's personal data was erased. Erasure also reaches that customer's earlier events: retries and resends that start after the erasure completes send `billingName`, `billingAddress`, `phone`, and the `email` of `customer.created` as `null`. Every other field keeps its first-attempt value, including `eventId`, amounts, timestamps, and `metadata`, and the signature covers the body that is sent. The event stays in Notification Center. `metadata` is not changed by erasure, so don't put buyer personal data in order metadata.
For what else erasure changes, see [Customer data erasure](/public-api#customer-data-erasure).

### Customers

| Event              | When it fires                                                                  | Payload                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer.created` | A **new** customer is created as a side effect of payment or membership ingest | `customerId` (Payments AI id), `email`, plus [buyer billing details](#buyer-billing-details). Creating a customer in the dashboard or API does **not** send this event. |

A customer created from a payment carries that payment's billing name and address. A customer created from a membership has no billing details yet, so `billingName` and `billingAddress` are `null` and `phone` is the membership's phone, when it has one and is still active; the buyer's billing details arrive on `payment.completed`.

```json
{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "eventType": "customer.created",
  "merchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "email": "customer@example.com",
  "billingName": "Dana Buyer",
  "billingAddress": { "country": "GB" },
  "phone": null
}
```

### Subscriptions

| Event                                 | When it fires                                                                     | Payload                                                                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription.created`                | Membership activates and local status is `active`                                 | `subscriptionId` (Payments AI id), `externalMembershipId`, `orderId` (nullable), `customerId` (nullable), `metadata`, plus billing state |
| `subscription.cancelled`              | The subscription ends: local status becomes `inactive`                            | `subscriptionId`, `externalMembershipId`, `orderId` (nullable), `customerId` (nullable), `metadata`, plus billing state                  |
| `subscription.updated`                | The billing state of an existing subscription changes                             | `subscriptionId` (Payments AI id), `orderId` (nullable), `customerId` (nullable), `metadata`, plus billing state                         |
| `subscription.cancellation_scheduled` | A cancellation at the end of the current period is scheduled                      | `subscriptionId` (Payments AI id), `orderId` (nullable), `customerId` (nullable), `metadata`, plus billing state                         |
| `subscription.cancellation_undone`    | A pending cancellation is withdrawn, so the subscription renews at the period end | `subscriptionId` (Payments AI id), `orderId` (nullable), `customerId` (nullable), `metadata`, plus billing state                         |
| `subscription.payment_method_updated` | The subscription's renewals move to another of the customer's saved cards         | `subscriptionId` (Payments AI id), `customerId` (nullable), `paymentMethodId` (Payments AI id), `brand` (nullable), `last4` (nullable)   |

Subscription events fire only for a purchase that bills as a subscription: a recurring plan, or an order with at least one recurring item, even when it also holds one-time items. A one-time or free-access purchase sends no subscription event, neither when it starts, nor when its access ends, nor when you change it through the Public API: a paid one-time purchase is announced by its [payment events](#payments), and a new buyer by `customer.created`. A purchase that has sent `subscription.created` keeps sending its subscription events until it ends.

`subscription.created` is always the first subscription event you receive for a subscription. When the provider's notice that the subscription started arrives late or not at all, the first change Payments AI receives sends `subscription.created` with the billing state at that moment, followed by the events of that change. A subscription that has already ended when Payments AI first hears of it sends no subscription event. A subscription sends `subscription.created` once per start: a repeated start notice for a subscription that has not ended sends none, while a subscription that ended and starts again sends a new one.

Every subscription event except `subscription.payment_method_updated` carries the subscription's billing state at top level. These are the same fields, with the same values, as the [subscription read](/public-api#read-subscriptions):

| Field                | Value                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `status`             | `active`, `trialing`, `canceling` (ends at the period end), or `inactive` (ended)               |
| `currentPeriodStart` | Start of the current billing period (nullable)                                                  |
| `currentPeriodEnd`   | End of the current billing period. During a trial, the trial end (nullable)                     |
| `nextChargeAt`       | When the next renewal charge is due. `null` for a pending cancellation or an ended subscription |
| `trialEndsAt`        | End of the free trial. `null` outside a trial                                                   |
| `cancelAtPeriodEnd`  | `true` when the subscription ends at the end of the current period                              |

`subscription.updated` is sent when any billing state field changes on a subscription Payments AI already holds: a renewal, a failed and retried renewal that moves the dates, a cancellation scheduled or withdrawn, a trial that converts or changes length. A membership update that changes none of these fields sends no `subscription.updated`. A late delivery that is older than the stored subscription sends nothing either. A subscription that started before `currentPeriodStart` and `nextChargeAt` were recorded has them `null` until its next membership update fills them; filling either one, or both together, sends no `subscription.updated`.

A new subscription sends `subscription.created`, not `subscription.updated`. Some changes send a pair of events, in this order: a cancellation sends `subscription.cancelled` then `subscription.updated`, an ended subscription that is re-activated sends `subscription.created` then `subscription.updated`, a cancellation scheduled for the period end sends `subscription.cancellation_scheduled` then `subscription.updated`, and a withdrawn cancellation sends `subscription.cancellation_undone` then `subscription.updated`. Subscribe only the events you need.

These events fire the same way whether the change came from your [Public API cancel or undo-cancel request](/public-api#cancel-a-subscription) or from the customer through the payment provider. A change is announced once: when you make it through the API, the provider's own notification of the same change sends nothing more, and a subscription that has already ended sends no second `subscription.cancelled`.

`subscription.updated`, `subscription.cancellation_scheduled` and `subscription.cancellation_undone` carry Payments AI ids only. They have no `externalMembershipId`.

Every subscription event except `subscription.payment_method_updated` also carries `metadata`: the object you sent when you [created the order](/multi-item-checkout#create-an-order), exactly as sent. It is read from the order named by `orderId`, and is `{}` when the order has no metadata or `orderId` is `null`.

```json
{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "eventType": "subscription.created",
  "merchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalMembershipId": "mem_XXXXXXXX",
  "orderId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "metadata": { "cart_order_number": "SO-10482" },
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "trialing",
  "currentPeriodStart": "2026-10-21T09:00:00.000Z",
  "currentPeriodEnd": "2026-10-28T09:00:00.000Z",
  "nextChargeAt": "2026-10-28T09:00:00.000Z",
  "trialEndsAt": "2026-10-28T09:00:00.000Z",
  "cancelAtPeriodEnd": false
}
```

`subscription.cancelled` has the same shape:

```json
{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "eventType": "subscription.cancelled",
  "merchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalMembershipId": "mem_XXXXXXXX",
  "orderId": null,
  "metadata": {},
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "inactive",
  "currentPeriodStart": "2026-10-21T09:00:00.000Z",
  "currentPeriodEnd": "2026-11-21T09:00:00.000Z",
  "nextChargeAt": null,
  "trialEndsAt": null,
  "cancelAtPeriodEnd": false
}
```

A cancellation scheduled for the period end sends `subscription.cancellation_scheduled`. `subscription.cancellation_undone` and `subscription.updated` have the same shape:

```json
{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "eventType": "subscription.cancellation_scheduled",
  "merchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "orderId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "metadata": { "cart_order_number": "SO-10482" },
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "canceling",
  "currentPeriodStart": "2026-10-21T09:00:00.000Z",
  "currentPeriodEnd": "2026-11-21T09:00:00.000Z",
  "nextChargeAt": null,
  "trialEndsAt": null,
  "cancelAtPeriodEnd": true
}
```

`subscription.payment_method_updated` is sent when a subscription's renewals move to another of the customer's saved cards: a [card change through the Public API](/public-api#set-a-subscriptions-card), for example with the card a [payment method session](/public-api#collect-a-new-card) saved. `paymentMethodId` is the card's `id` in the customer's [saved cards](/public-api#list-a-customers-saved-cards). The event carries the card's `brand` and `last4` only, never the card number or its expiry, and no billing state. Setting the card a subscription already has sends nothing, and the payment provider's own notification of the change sends nothing more. When the change also moves the billing state, `subscription.updated` follows it.

```json
{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "eventType": "subscription.payment_method_updated",
  "merchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "paymentMethodId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "brand": "visa",
  "last4": "4242"
}
```

### Disputes

| Event                   | When it fires                              | Payload                                                                                                                                                                                       |
| ----------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dispute.created`       | A dispute is opened                        | `disputeId` (Payments AI id), `externalDisputeId`, `amount`, `currency`, `reason`                                                                                                             |
| `dispute.updated`       | Dispute updates and status is not won/lost | Same as created, plus `status`                                                                                                                                                                |
| `dispute.won`           | Dispute status becomes won                 | `disputeId`, `externalDisputeId`, `amount`, `currency`                                                                                                                                        |
| `dispute.lost`          | Dispute status becomes lost                | `disputeId`, `externalDisputeId`, `amount`, `currency`                                                                                                                                        |
| `dispute.alert_created` | A dispute alert is created                 | `alertId` (Payments AI id), `externalAlertId`, `transactionId` (Payments AI id, nullable), `externalTransactionId`, `alertType` (`Dispute` / `RDR` / `Fraud`), `reason`, `amount`, `currency` |

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f1",
  "eventType": "dispute.created",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "disputeId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3b",
  "externalDisputeId": "dp_XXXXXXXX",
  "amount": 25,
  "currency": "usd",
  "reason": "duplicate"
}
```

`dispute.alert_created` has a distinct shape. `transactionId` is `null` when the alert can't be linked to a known transaction yet:

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f2",
  "eventType": "dispute.alert_created",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "alertId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3c",
  "externalAlertId": "alrt_XXXXXXXX",
  "transactionId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3b",
  "externalTransactionId": "pay_XXXXXXXX",
  "alertType": "Dispute",
  "reason": "duplicate",
  "amount": 25,
  "currency": "usd"
}
```

### Payouts

| Event         | When it fires                     | Payload                                                                             |
| ------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
| `payout.sent` | Withdrawal status is `in_transit` | `payoutId` (Payments AI id), `externalWithdrawalId`, `status`, `amount`, `currency` |

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f3",
  "eventType": "payout.sent",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-000000000001",
  "payoutId": "018f2b1a-9c3e-7d21-8b4a-2f6e1c9a0d3d",
  "externalWithdrawalId": "wth_XXXXXXXX",
  "status": "in_transit",
  "amount": 100.0,
  "currency": "usd"
}
```

### Merchants

| Event                     | When it fires                                                                               | Payload                                                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant.owner_attached` | A seller claims a merchant through its owner-claim join link                                | `merchantId` (the claimed merchant), `ownerUserId` (Payments AI id), `email` (the owner's sign-in email)                                                                        |
| `merchant.kyc.updated`    | A seller's identity verification (KYC) status changes after the payment provider reports it | `merchantId`, `kycStatus`, `previousKycStatus`, `activationStatus`, `occurredAt` (ISO 8601 UTC). Status enums match `GET /v1/public-api/merchants/{merchantId}` `activation.*`. |

Only a join link claim sends `merchant.owner_attached`. An owner attached when the merchant is created, or assigned through the Merchant Public API members route, does not — those responses already say so. To receive it for sub-merchants you created, subscribe an endpoint on your **parent** merchant and enable **Receive sub-merchant events**. See [Platform onboarding](/platform-onboarding).

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f4",
  "eventType": "merchant.owner_attached",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-0000000000ab",
  "ownerUserId": "0193a1b2-c3d4-7e5f-8000-0000000000cd",
  "email": "founder@acmecoaching.com"
}
```

`merchant.kyc.updated` fires only when the stored KYC status actually changes (for example `in_review` → `verified`). Repeat provider deliveries with the same status, or downgrades after the merchant is already verified, do not emit. To receive it for sub-merchants you created, subscribe an endpoint on your **parent** merchant and enable **Receive sub-merchant events**. You can also poll `GET /v1/public-api/merchants/{merchantId}/kyc`. See [Platform onboarding](/platform-onboarding#6-identity-verification-kyc).

```json
{
  "eventId": "0193a1b2-c3d4-7e5f-8000-0000000000f5",
  "eventType": "merchant.kyc.updated",
  "merchantId": "0193a1b2-c3d4-7e5f-8000-0000000000ab",
  "kycStatus": "verified",
  "previousKycStatus": "in_review",
  "activationStatus": "active",
  "occurredAt": "2026-10-26T12:34:56.789Z"
}
```

## Next steps

- [Merchant Public API](/public-api)
- [Webhook destination not found](/errors/webhook-destination-not-found)
- [Webhook URL forbidden](/errors/webhook-destination-url-forbidden)
- [Getting help](/getting-help)
- [Quickstart](/quickstart)
