{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000023",
  "type": "CARD.PIN_STATUS_CHANGE",
  "timestamp": "2026-05-09T10:00:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "status": "ACTIVE",
    "pinStatus": "BLOCKED",
    "brand": "VISA",
    "form": "VIRTUAL",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "maxSpendPerTransaction": null,
    "maxSpendPerDay": null,
    "maxTransactionsPerDay": null,
    "currency": "USD",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

Webhooks

Card pin status change

Sent when Grid records a change to a card’s PIN status, including changes detected after a hosted PIN submission, an API request, or a PIN becoming blocked. The data contains the updated Card resource and its new pinStatus.

Initial card creation does not trigger this event. Changing an existing PIN while its status remains OK does not trigger it either; use the submission result to confirm that the PIN changed.

Changes made outside the Grid API are detected asynchronously. The event describes the status Grid observed, not every intermediate PIN status. Delivery can be repeated or arrive out of order. Deduplicate by id and use data.updatedAt to avoid replacing newer card data with an older snapshot. Read pinStatus from GET /cards/ to retrieve the card’s saved status.

Verify the X-Grid-Signature header using your Grid webhook public key, as for other Grid webhooks. No PIN, encrypted PIN block, or PIN-entry session credential is included.

WEBHOOK

card-pin-status-change

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000023",
  "type": "CARD.PIN_STATUS_CHANGE",
  "timestamp": "2026-05-09T10:00:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "status": "ACTIVE",
    "pinStatus": "BLOCKED",
    "brand": "VISA",
    "form": "VIRTUAL",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "maxSpendPerTransaction": null,
    "maxSpendPerDay": null,
    "maxTransactionsPerDay": null,
    "currency": "USD",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

Authorizations

X-Grid-Signature

string

header

required

Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid. To verify the signature:

Get the Grid public key provided to you during integration
Decode the base64 signature from the header
Create a SHA-256 hash of the request body
Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

Body

application/json

string

required

Unique identifier for this webhook delivery (can be used for idempotency)

Example:

"Webhook:019542f5-b3e7-1d02-0000-000000000007"

type

enum<string>

required

Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED)

Available options:

CARD.PIN_STATUS_CHANGE

timestamp

string<date-time>

required

ISO 8601 timestamp of when the webhook was sent

Example:

"2025-08-15T14:32:00Z"

data

object

required

The updated card, including its new pinStatus.

Show child attributes

Response

Webhook received successfully

Using the API

API documentation

Card pin status change

Authorizations

Body

Response