Webhooks
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:
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. |
{
"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.
Payloads contain ids, amounts, and emails. They never include raw card data.
Create a destination
- Sign in to the Payments AI dashboard.
- Open Developer Tools → Webhooks.
- Enter a public HTTPS URL, select the events you want, and optionally add custom headers.
- 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.
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.
- On the parent merchant, open Developer Tools → Webhooks.
- When you add an endpoint, enable Receive sub-merchant events. You can also turn this on later from the Webhooks table.
- 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.
import { createHmac, timingSafeEqual } from 'node:crypto';
const WEBHOOK_SECRET = process.env.PAI_WEBHOOK_SECRET!;
export function verifyPaymentsAiWebhook(params: {
rawBody: string;
timestamp: string;
signatureHeader: string;
}): boolean {
const { rawBody, timestamp, signatureHeader } = params;
const expected =
'sha256=' +
createHmac('sha256', WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');
const actual = Buffer.from(signatureHeader);
const expectedBuf = Buffer.from(expected);
if (actual.length !== expectedBuf.length) {
return false;
}
return timingSafeEqual(actual, expectedBuf);
}
// Read the raw request body as a string before JSON.parse.
// Headers: X-Webhook-Timestamp, X-Webhook-Signature
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.
{
"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 or Cloudflare Tunnel. 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 toX-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 and confirm the URL is still public (Webhook 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). 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 |
payment.failed | Payment fails | transactionId (Payments AI id), externalTransactionId, occurredAt, orderId (nullable), customerId (nullable), subscriptionId (nullable), metadata, declineReason (nullable), plus 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, 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.
{
"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}. 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.
{
"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.
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. 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.
{
"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, 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:
| 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 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, exactly as sent. It is read from the order named by orderId, and is {} when the order has no metadata or orderId is null.
{
"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:
{
"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:
{
"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, for example with the card a payment method session saved. paymentMethodId is the card's id in the customer's 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.
{
"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 |
{
"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:
{
"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 |
{
"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.
{
"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.
{
"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"
}