Card Events

1. Purpose

This webhook allows third-party partners to receive real-time card status updates from VaultsPay. Partners register a single callback URL, and VaultsPay sends a POST request to that URL whenever an important card status change occurs.

The payload is intentionally lean, containing only the essential information required for partners to update their systems.

2. How Integration Works

1. Partner registers a webhook URL and optional secret in the SaaS platform.
2. VaultsPay stores the subscription in the webhook system.
3. When a card status changes, the event is produced by internal services.
4. The webhook dispatcher sends the event to the partner’s URL.

3. Webhook Payload

Example webhook request sent to partners:

{
  "id": "01hvjr8fz6mbw6f9r9v3e5b5yw",
  "type": "card.status.active",
  "occurred_at": "2026-03-13T09:20:12Z",
  "status": {
    "previous": {
      "code": "BLOCK",
      "label": "DECLINE_ALL_TXNS"
    },
    "current": {
      "code": "ACTIVE",
      "label": "FULLY_OPERATIONAL"
    },
    "reason": "Card was unblocked by the admin"
  },
  "card": {
    "token": 987654321,
    "last_four_digits": "3321",
    "tier": "VaultsPay Debit Card Tier",
    "network": "MC",
    "type": "PHYSICAL"
  }
}

4. Key Fields

Envelope

Status Change

Card Information

This structure allows partners to track the status transition clearly while keeping the payload minimal.

5. Card Status Events Sent to Partners

VaultsPay sends webhooks only for important lifecycle states.

6. Enumerations

6.1 Status Codes (status.previous.code, status.current.code)

Platform-level card states:

6.2 Status Labels (status.previous.label, status.current.label)

Network-level behavior:

6.3 Code → Label Mapping Rule

This mapping is deterministic and guaranteed:

This applies to both status.previous and status.current.

6.4 Mapping Between type and Status Transitions

6.5 Card Type (card.type)

6.6 Card Network (card.network)