Card Management

Learn how to manage virtual cards after issuance, including freezing, unfreezing, terminating, and monitoring card status.

Overview

Once you have issued cards, you need to manage their lifecycle effectively. This guide covers all post-issuance card operations including status management, security controls, and card termination.

Prerequisites

• An existing issued card (see Card Issuance guide)
• Valid API token with card management permissions
• Card ID from the issuance process

Card Status Management

Get Card Information

First, retrieve current card information to check its status:

curl -X GET https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012 \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}"

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "ACTIVE",
  "name": "Corporate Card",
  "cardHolderName": "John Doe",
  "lastFour": "1234",
  "expirationDate": "2027-12",
  "availableAmount": {
    "amount": "4750.00",
    "currency": "USD"
  },
  "spendingLimit": {
    "name": "MONTHLY",
    "limit": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "spentAmount": {
      "amount": "250.00",
      "currency": "USD"
    }
  },
  "securityPolicy": {
    "internet": true,
    "ecommerce": true,
    "contactless": false,
    "atm": false,
    "location": false
  },
  "activatedAt": "2025-07-04T15:32:00Z"
}

List All Cards

Get all cards for your business:

curl -X GET https://api.brighty.codes/business/v1/cards \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}"

Response:

{
  "cards": [
    {
      "id": "card_12345678-1234-1234-1234-123456789012",
      "status": "ACTIVE",
      "name": "Corporate Card",
      "cardHolderName": "John Doe",
      "lastFour": "1234"
    },
    {
      "id": "card_87654321-4321-4321-4321-210987654321",
      "status": "FROZEN",
      "name": "Travel Card",
      "cardHolderName": "Jane Smith",
      "lastFour": "5678"
    }
  ]
}

Card Status Operations

Freeze Card (Temporary Suspension)

Temporarily disable a card while keeping it recoverable:

curl -X POST https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/freeze \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "FROZEN",
  "statusReason": "REQUESTED_BY_CUSTOMER",
  "frozenAt": "2025-07-04T16:00:00Z"
}

Use cases for freezing:

• Suspicious activity detected
• Card temporarily lost
• Precautionary measure during investigation
• User request for temporary suspension

Unfreeze Card

Reactivate a frozen card:

curl -X POST https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/unfreeze \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "ACTIVE",
  "statusReason": null,
  "unfrozenAt": "2025-07-04T16:15:00Z"
}

Terminate Card (Permanent Deactivation)

Permanently disable a card (cannot be reversed):

curl -X POST https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/terminate \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "TERMINATED",
  "statusReason": "REQUESTED_BY_CUSTOMER",
  "terminatedAt": "2025-07-04T16:30:00Z"
}

Use cases for termination:

• Employee leaves company
• Card permanently lost or stolen
• End of card lifecycle
• Security breach requiring permanent deactivation

Card Status Flow

CREATED → ISSUED → ACTIVE ⟷ FROZEN
   ↓         ↓       ↓        ↓
   TERMINATED ← ← ← ← ← ← ← ← ←

Status Descriptions

• CREATED: Card ordered, being processed by card provider
• ISSUED: Card issued by provider, ready for activation
• ACTIVE: Card activated and ready for transactions
• FROZEN: Card temporarily suspended (reversible)
• TERMINATED: Card permanently disabled (irreversible)

Status Transitions

From	To	Action	Reversible
CREATED	ISSUED	Automatic	No
ISSUED	ACTIVE	Manual activation	No
ACTIVE	FROZEN	Manual freeze	Yes
FROZEN	ACTIVE	Manual unfreeze	Yes
Any	TERMINATED	Manual termination	No

Card Customization

Rename Card

Update the card's display name for better organization:

curl -X PATCH https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/rename \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Department Card"
  }'

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "name": "Marketing Department Card"
}

Security Features

Get Card Security Policies

Check current security settings:

curl -X GET https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/security \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}"

Response:

{
  "cardId": "card_12345678-1234-1234-1234-123456789012",
  "securityPolicy": {
    "internet": true,
    "ecommerce": true,
    "contactless": false,
    "atm": false,
    "location": false
  },
  "spendingLimits": {
    "daily": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "monthly": {
      "amount": "5000.00",
      "currency": "USD"
    }
  }
}

Access Card Credentials

Get secure access to card details (PCI compliant):

curl -X POST https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/credentialsUri \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "uri": "https://secure.brighty.app/cards/credentials?token=eyJ0eXAiOiJKV1QiLCJhbGciOi...",
  "expiresAt": "2025-07-04T17:00:00Z"
}

Note: The URI provides secure, time-limited access to card number, CVV, and expiry date.