API Docs

Callback Events

Security Note: Callbacks can only be managed using your Secret API Key, not your Public Key. This is for security purposes, as callbacks have access to sensitive event data.

When setting up a callback, you need to specify which events you want to subscribe to. Multiple events can be specified as a comma-separated list. Below is a comprehensive list of all events you can subscribe to.

Payment Events

payment.created

Triggered when a new payment is created but not yet processed.

payment.updated

Triggered when payment details are updated.

payment.completed

Triggered when a payment is successfully completed.

payment.failed

Triggered when a payment fails to process.

payment.refunded

Triggered when a payment is refunded, either partially or fully.

payment.disputed

Triggered when a payment is disputed by the customer.

Payout Events

payout.created

Triggered when a new payout is created.

payout.updated

Triggered when payout details are updated.

payout.completed

Triggered when a payout is successfully completed.

payout.failed

Triggered when a payout fails to process.

payout.canceled

Triggered when a payout is canceled.

Customer Events

customer.created

Triggered when a new customer is created.

customer.updated

Triggered when customer details are updated.

customer.deleted

Triggered when a customer is deleted.

Payment Link Events

payment_link.created

Triggered when a new payment link is created.

payment_link.updated

Triggered when a payment link is updated.

payment_link.deleted

Triggered when a payment link is deleted.

payment_link.visited

Triggered when a payment link is visited by a customer.

Subscription Events

subscription.created

Triggered when a new subscription is created.

subscription.updated

Triggered when a subscription is updated.

subscription.canceled

Triggered when a subscription is canceled.

subscription.renewed

Triggered when a subscription is renewed for a new billing period.

subscription.payment_failed

Triggered when a payment for a subscription fails.

subscription.payment_succeeded

Triggered when a payment for a subscription succeeds.

Webhook Delivery

When an event occurs, our system will send a POST request to the URL you specified when creating the callback. The request will include an Event object in the body with the following structure:

{
  "id": "zp_event_1234567890",
  "type": "payment.completed",
  "created": "2023-01-15T14:30:45Z",
  "data": {
    "object": {
      // The object related to this event (e.g., payment, payout, customer)
      "id": "payment_abc123",
      // ... other object properties
    }
  }
}

Handling Webhook Failures

If our system fails to deliver a webhook (e.g., if your server responds with a non-2XX status code), we'll automatically retry several times with an exponential backoff strategy. After multiple consecutive failures, the callback will be marked as failing and you'll need to update it or fix your endpoint.