Partner Webhook Events

Partner webhooks can be set up and managed using Stax API. Their clients can be referred to as merchants, or sub-merchants in Stax. Each partner/ISV has a unique brand, and all of their sub-merchants have the partner's brand.

A partner-level webhook triggers for all merchants under a specific brand. For example, setting up the update_merchant_status partner webhook ensures that any time a merchant under the partner's brand is activated in Stax, the webhook will fire.

Payment Related Webhook Events

Webhook	Description
create_dispute	Triggered when a dispute is created. Returns the dispute object.
create_deposit	Triggered when a settlement (deposit) is processed. Returns the settlement record. The `external_id` in the payload connects the deposit record to the deposit details. Note: This webhook fires in both production and sandbox environments, but in sandbox, the `external_id` will not match the `batch_id`. Use this webhook as a notification and then call the merchant's deposit APIs to retrieve the latest deposit details.
create_invoice	Triggered when a new invoice is created, including invoices created by an invoice schedule. Returns the invoice object.
create_payment_method	Triggered when a new payment method is created. Returns the payment method object.
create_transaction	Triggered when a new transaction is created, including transactions created via Stax.js. Returns the transaction object.
create_user	Triggered when a new user is created. Returns the user object.
update_dispute	Triggered when a dispute is updated, such as when the dispute status changes. Returns the updated dispute object.
update_payment_method	Triggered when a payment method is updated. Returns the updated payment method object. The update may originate from an action by the merchant user or from Stax updating information via account updater services.
update_transaction	Triggered when a transaction is updated. Returns the updated transaction object. Note: This does not fire when a transaction's `settled_at` date is added. For ACH transactions, use the`update_transaction_settled`.
update_transaction_settled	Triggered when an ACH transaction has settled or not settled. Returns the original transaction object. If the transaction settled, the `settled_at` date will be populated. If the transaction was clawed back, the `child_transactions` array will include the associated void transaction. For more details on ACH settlement, refer to our ACH documentation.

Merchant Enrollment Webhook Events

Webhook	Description
create_merchant	Triggered when a new merchant is created under the partner brand. This is particularly useful for partners utilizing the Stax Landing Page Enrollment option. Returns the merchant object.
update_underwriting	Triggered when a merchant registration's underwriting status changes, including `underwriting_status`, `underwriting_substatuses`, or `underwriting_note`. Continue listening to this webhook until `registration.underwriting_status` is `APPROVED`. Returns the merchant's registration object.
update_merchant_status	Triggered when a merchant's status changes. When `merchant.status` is set to `ACTIVE`, the merchant can begin processing payments. Returns the merchant object.
update_electronic_signature	Triggered when a merchant signer has signed their merchant application. Returns the merchant's registration object. Triggered by changes to the `registration.electronic_signature` value.

Implementing Webhooks

Webhook Payload

Each webhook POST request contains:

Headers:

stax-event-name: The name of the event that triggered the webhook. This correlates to the event_name specified when setting up the webhook.

Body:

The associated object related to the event (e.g., transaction object for create_transaction).

All endpoints accept and return JSON.

Retry Logic

You can specify optional metadata when creating a webhook to control retry behavior:

meta.response_body: Set to true to enable a webhook failure to retry once after five minutes.
meta.webhook_retry_frequency: Define how frequently (in minutes) the webhook should retry.
meta.webhook_retry_count: Define how many times the webhook should retry upon failure.

Example

{
  "meta": {
    "response_body": true,
    "webhook_retry_frequency": 5,
    "webhook_retry_count": 3
  }
}