card.bound
Physical card bound, waiting for activation
When Emitted
Sent after bind finishes and the card row exists. POST /v1/cards/bind returning binding only means the request was accepted; a card row may not exist yet, so this event is not sent with that response.
data.id is the public card id (crd_<id>). Retrieve it with GET /v1/cards/{data.id}.
status is the card status, unactivated when bind has just completed.
application_id (cap_<id>) is included when the card came from an application, and omitted otherwise.
This is not activation. Activation is reported by card.application.approved and card.status.updated. Automatic activation is reported by card.activated.
Sent once per card. The payload does not include the card number, expiry, security code, or PIN.
⚠ Not sent for platform-direct members.
Payload
{
"event_id": "evt_c4d8e21b0a6f4d7e9b15c3a28f06d441",
"event_type": "card.bound",
"created_at": "2026-10-19T16:48:34Z",
"merchant_id": "acme",
"livemode": true,
"data": {
"object": "card",
"id": "crd_e70b3d41-5a28-4c96-91f0-6b2a8c05d7e3",
"external_member_id": "u_88123",
"status": "unactivated",
"status_version": 1,
"application_id": "cap_9c41f0a8-27d5-4e63-b0a9-1f7c85d2e340"
}
}
Payload Fields
| Field | Type | Description |
|---|---|---|
id | string | Use this for deduplication. evt_… remains unchanged when the same event is redelivered. |
type | string | Always card.bound |
created_at | string | Time the event was created (RFC3339), not its delivery time. It is unchanged on redelivery. |
data.object | string | Object type; determines which endpoint to query with data.id |
data.id | string | Object ID; use it to retrieve details. |
data.status | string | Treat unrecognized values as unknown and raise an alert; do not fall back to “processing” |
data.status_version | number | Monotonically increasing; use it to discard older states that arrive late. |
Signature Verification and Deduplication
Verify the signature against the raw request body bytes. Do not parse and reserialize the JSON: your JSON library may change key order or whitespace, which changes the signature and can look like a key configuration error.
// Node · Run before parsing JSON
const raw = await readRawBody(req); // Buffer / string; do not use parsed req.body
const expect = crypto.createHmac("sha256", WEBHOOK_SECRET).update(raw).digest("hex");
const got = req.headers["z-signature"]; // Format: t=<unix>,v1=<hex>
if (!timingSafeEqual(expect, parseV1(got))) return res.status(400).end();
// Deduplicate using the envelope id, not data.id
if (await seen(JSON.parse(raw).id)) return res.status(200).end();
For the full procedure, including timestamp tolerance and redelivery semantics, see Webhook Guide.