Merchant Lifecycle Events

Notifications for merchant onboarding lifecycle events - merchant application progress, merchant approval decisions, and pricing template review decisions.

All merchant lifecycle events share one payload shape: an event envelope (id, type, timestamp, and the related merchant id once one exists) and a data section with the application, status transition, and pricing template details that apply to the event type. Fields that do not apply are null, so branch on the envelope's type rather than on the presence of a field.

Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.

Beta. Merchant lifecycle events are in beta: the set of events and the payload can still change, and breaking changes are announced with a deprecation period.

Merchant lifecycle events are delivered on Svix webhooks only, never on legacy webhooks. Svix webhooks are invite only; see Svix webhooks.

Delivery, retries and signature verification work exactly as for transaction events. See Webhooks.

Merchant application started

POSTMerchantApplicationStarted to your webhook endpoint

This webhook event is triggered when a merchant begins filling out their onboarding application. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the merchant.application.started webhook event.

application/json · MerchantApplicationStartedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PA",
    "type": "merchant.application.started",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": null,
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": "Created",
    "toStatus": "InProgress",
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant application submitted

POSTMerchantApplicationSubmitted to your webhook endpoint

This webhook event is triggered when a merchant submits their onboarding application for review. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.application.submitted webhook event.

application/json · MerchantApplicationSubmittedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PB",
    "type": "merchant.application.submitted",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": "WaitingForSigning",
    "toStatus": "Submitted",
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant application status changed

POSTMerchantApplicationStatusChanged to your webhook endpoint

This webhook event is triggered when a merchant application moves between review stages (e.g. into Underwriting or Onboarding). Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.application.status_changed webhook event.

application/json · MerchantApplicationStatusChangedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PC",
    "type": "merchant.application.status_changed",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": "Submitted",
    "toStatus": "Underwriting",
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant application requires action

POSTMerchantApplicationRequiresAction to your webhook endpoint

This webhook event is triggered when a merchant application needs more information or documents from the merchant before review can continue. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.application.requires_action webhook event.

application/json · MerchantApplicationRequiresActionWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PD",
    "type": "merchant.application.requires_action",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": null,
    "toStatus": null,
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant application information uploaded

POSTMerchantApplicationInfoUploaded to your webhook endpoint

This webhook event is triggered when a merchant provides the requested information or documents on an application that required action. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.application.info_uploaded webhook event.

application/json · MerchantApplicationInfoUploadedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PE",
    "type": "merchant.application.info_uploaded",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": null,
    "toStatus": null,
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant approved

POSTMerchantApproved to your webhook endpoint

This webhook event is triggered when a merchant application is approved and the merchant account is created. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.approved webhook event.

application/json · MerchantApprovedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PF",
    "type": "merchant.approved",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": null,
    "toStatus": null,
    "reason": null,
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Merchant rejected

POSTMerchantRejected to your webhook endpoint

This webhook event is triggered when a merchant application is rejected during review. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the merchant.rejected webhook event.

application/json · MerchantRejectedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PG",
    "type": "merchant.rejected",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": "Blue Bottle Bakery",
    "applicationId": "map_01JZM7RH2M8S6WV0P9RQD37GXE",
    "fromStatus": "Underwriting",
    "toStatus": "Rejected",
    "reason": "The business category is not supported for card-present processing.",
    "templateName": null,
    "templateRegion": null,
    "templateVersion": null,
    "portalLink": "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Pricing template approved

POSTPricingTemplateApproved to your webhook endpoint

This webhook event is triggered when a submitted pricing template is approved in review and its onboarding links become active. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the pricing_template.approved webhook event.

application/json · PricingTemplateApprovedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PH",
    "type": "pricing_template.approved",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": null,
    "applicationId": null,
    "fromStatus": null,
    "toStatus": null,
    "reason": null,
    "templateName": "Standard US Card-Present",
    "templateRegion": "US",
    "templateVersion": "3",
    "portalLink": "https://portal.example.com/settings/onboarding-links"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}

Pricing template rejected

POSTPricingTemplateRejected to your webhook endpoint

This webhook event is triggered when a submitted pricing template is declined in review. Delivered on Svix webhooks only, never on legacy webhooks. In beta, so the payload can still change.

Parameters

Name In Type Description

svix-id

header

string

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestamp

header

string

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signature

header

string

Payload

The request body for the pricing_template.rejected webhook event.

application/json · PricingTemplateRejectedWebhook

event object required

Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.

Child attributes

id string required

Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no evt_ prefix.

Example: "01JZM7Q2XVGT5H8RC3W9K4N6PD"

type string required

The type of event that occurred.

Example: "merchant.application.submitted"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2026-07-09T14:30:00Z"

merchantId string required nullable

The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events).

Example: "mer_01M25WWARK63SVEMXZJ5Y8ZSQK"

data MerchantLifecycleWebhookData required

Child attributes

isvId string required

Your account ID, prefixed with isv_.

Example: "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD"

merchantName string required nullable

The merchant's business display name, when known.

Example: "Blue Bottle Bakery"

applicationId string required nullable

The merchant onboarding application this event relates to.

Example: "map_01JZM7RH2M8S6WV0P9RQD37GXE"

fromStatus string required nullable

The application status before the transition, for application progress events.

Example: "WaitingForSigning"

toStatus string required nullable

The application status after the transition, for application progress events.

Example: "Submitted"

reason string required nullable

Human-readable reason accompanying a rejection decision, when one was provided.

Example: null

templateName string required nullable

The pricing template name, for pricing template decision events.

Example: null

templateRegion string required nullable

The pricing template region (US or CA), for pricing template decision events.

Example: null

templateVersion string required nullable

The pricing template version, for pricing template decision events.

Example: null

portalLink string (uri) required

Deep link into the partner portal page for this event.

Example: "https://portal.example.com/merchants/applications/map_01JZM7RH2M8S6WV0P9RQD37GXE"

Example

{
  "event": {
    "id": "01JZM7Q2XVGT5H8RC3W9K4N6PJ",
    "type": "pricing_template.rejected",
    "timestamp": "2026-07-09T14:30:00Z",
    "merchantId": null
  },
  "data": {
    "isvId": "isv_01JY9FCPM8Q5T2V7R4W1XKB6ZD",
    "merchantName": null,
    "applicationId": null,
    "fromStatus": null,
    "toStatus": null,
    "reason": "Credit card discount rate exceeds the approved range for this region.",
    "templateName": "Standard US Card-Present",
    "templateRegion": "US",
    "templateVersion": "3",
    "portalLink": "https://portal.example.com/settings/onboarding-links"
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse

{}