customer.restricted

customer.restricted is off by default. It will not be delivered until you enable it in Dashboard → Developers. See Receiving Webhooks for instructions.

Fired when a customer’s deposit or withdrawal access is restricted inside Soap — by a dashboard user or by automated checks (for example KYC failure or multi-accounting). The matching lift is customer.unrestricted, which uses the same payload shape. This is a customer event, not a checkout event. The payload has no charge, line_items, or subscription fields.

Payload Structure

interface WebhookEvent {
  event_id: string;
  data: {
    customer: {
      id: string;
    };
    type: "deposit_restricted" | "withdrawal_restricted";
    reason_code: string | null;
    created_at: string;
    user: {
      email: string;
    } | null;
  };
  type: "customer.restricted";
}

type is which restriction flag changed, not the webhook event name.
user is { "email": "..." } when a dashboard user applied the restriction, and null when Soap applied it automatically.
created_at is a Ruby-formatted timestamp string ("2026-08-25 18:20:59 UTC"), not ISO 8601.

Example Response

{
  "event_id": "ev_tDaWu5aTVa2kbvDjGe55rxZpaMEmVFWB",
  "data": {
    "customer": {
      "id": "cus_5cDuRGp9AvscMgoyS5Y7wygiTgQrycvs"
    },
    "type": "deposit_restricted",
    "reason_code": "KYC_FAILED",
    "created_at": "2026-08-25 18:20:59 UTC",
    "user": null
  },
  "type": "customer.restricted"
}

Dashboard-initiated example, with an acting user:

{
  "event_id": "ev_tDaWu5aTVa2kbvDjGe55rxZpaMEmVFWB",
  "data": {
    "customer": {
      "id": "cus_5cDuRGp9AvscMgoyS5Y7wygiTgQrycvs"
    },
    "type": "withdrawal_restricted",
    "reason_code": null,
    "created_at": "2026-08-25 18:20:59 UTC",
    "user": {
      "email": "ops@example.com"
    }
  },
  "type": "customer.restricted"
}

API Documentation

API Endpoints

Webhooks

Testing

customer.restricted

Payload Structure

Example Response

​Payload Structure

​Example Response

Payload Structure

Example Response