Card Issuing & Lifecycle Management

Rook provides complete programmatic control over virtual and physical card issuance. Cards are issued against depository wallets under a specific program tenant, with instantaneous activation and real-time spending controls.

In compliance with PCI DSS standards, raw Primary Account Numbers (PAN) and Card Verification Values (CVV) are never returned in card objects. Card responses contain last_four, expiration_month, and expiration_year.

Card Form Factors

Form Factor	Delivery	Instant Activation	Use Cases
`VIRTUAL`	Instant via API	Yes (immediate)	E-commerce, subscriptions, digital ad spend, employee expense cards.
`PHYSICAL`	Shipped to address	Upon carrier delivery & activation	Corporate travel, field team expense cards, fleet fueling.

Issuing a Card

To issue a card, call POST /v1/cards with your program tenant header X-Program-ID and an Idempotency-Key.

curl -X POST "https://api.sandbox.rookpayments.com/v1/cards" \
  -H "Authorization: Bearer rk_test_..." \
  -H "X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Idempotency-Key: e82f3a10-4c7b-4192-881b-9a4f2c019d33" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "4d8f2a10-6c3e-4b91-9e5a-2f7c8d1e0b44",
    "wallet_entity_id": "ent_992a7c81-4b10-4c8e-a719-882d9f10a823",
    "form_factor": "VIRTUAL",
    "display_name": "Corporate Cloud Infrastructure",
    "spending_controls": {
      "limit_amount": 250000,
      "limit_currency": "USD",
      "limit_period": "MONTHLY",
      "allowed_mcc_codes": ["5734", "7372", "7379"]
    }
  }'

Sample Response (`201 Created`)

{
  "object": "card",
  "id": "crd_8f162a7b-4d93-4e1b-b5e1-8f3a6c9d0142",
  "wallet_id": "4d8f2a10-6c3e-4b91-9e5a-2f7c8d1e0b44",
  "wallet_entity_id": "ent_992a7c81-4b10-4c8e-a719-882d9f10a823",
  "program_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "state": "OPEN",
  "form_factor": "VIRTUAL",
  "display_name": "Corporate Cloud Infrastructure",
  "last_four": "4892",
  "bin": "411111",
  "expiration_month": 12,
  "expiration_year": 2029,
  "spending_controls": {
    "limit_amount": 250000,
    "limit_currency": "USD",
    "limit_period": "MONTHLY",
    "allowed_mcc_codes": ["5734", "7372", "7379"]
  },
  "created_at": "2026-09-10T14:22:00Z",
  "updated_at": "2026-09-10T14:22:00Z"
}

Card State Machine

Cards transition through deterministic lifecycle states:

[ CREATION ] ──> PENDING_ACTIVATION ──> OPEN <──> FROZEN
                      │                  │
                      └───> TERMINATED <─┘

State	Spend Enabled?	Actions Allowed	Transition Notes
`PENDING_ACTIVATION`	No	Activate, Cancel	Initial state for physical cards awaiting carrier delivery.
`OPEN`	Yes	Freeze, Terminate, Update Controls	Active and ready for authorizations.
`FROZEN`	No (declined)	Unfreeze, Terminate	Temporary freeze by cardholder or administrator. Instant edge broadcast.
`TERMINATED`	No (hard decline)	None (terminal)	Irrevocably destroyed. Cannot be reopened.

Freezing and Unfreezing a Card

To freeze a card (e.g., in response to suspected compromise or temporary policy lock), call PATCH /v1/cards/{card_id}:

curl -X PATCH "https://api.sandbox.rookpayments.com/v1/cards/crd_8f162a7b-4d93-4e1b-b5e1-8f3a6c9d0142" \
  -H "Authorization: Bearer rk_test_..." \
  -H "X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FROZEN",
    "freeze_reason": "Suspicious merchant charge reported by user"
  }'

Spending Controls & Velocity Enforcements

Rook supports fine-grained control rules evaluated at authorization time with sub-100ms latency:

Amount & Period Limits: Specify limit_amount in integer minor currency units (e.g., 250000 = $2,500.00 USD). Supported periods: TRANSACTION, DAILY, WEEKLY, MONTHLY, LIFETIME.
Merchant Category Code (MCC) Controls: Pass allowed_mcc_codes to enforce strict allowlisting (all other categories declined), or blocked_mcc_codes to block specific categories (e.g., gambling 7995, crypto 6051).
Country Controls: Restrict transactions to specific merchant countries via ISO 3166-1 alpha-2 codes.
Card-Not-Present (CNP) Controls: Disable or enable online/e-commerce authorizations independently of point-of-sale chip transactions.