> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Card Status

> Retrieve the current status and details of the authenticated user's card

## Overview

Retrieves comprehensive information about the authenticated user's card, including its current status, holder details, expiry date, and card type. This endpoint is essential for checking card availability and displaying card information in your application.

<Info>
  This endpoint returns basic card information only. Sensitive details like the full PAN, CVV, and PIN are never exposed through this endpoint. Use the secure token-based endpoints for accessing sensitive information.
</Info>

## Authentication

This endpoint requires authentication via Bearer token:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="x-us-env" type="boolean" default={false}>
  Set to `true` to route requests to the US backend environment
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://dev.api.baanx.com/v1/card/status \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  const cardStatus = await response.json();
  console.log(cardStatus);
  ```

  ```python Python theme={null}
  import requests

  url = "https://dev.api.baanx.com/v1/card/status"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  interface CardStatus {
    id: string;
    holderName: string;
    expiryDate: string;
    panLast4: string;
    status: 'ACTIVE' | 'FROZEN' | 'BLOCKED';
    type: 'VIRTUAL' | 'PHYSICAL' | 'METAL';
    orderedAt: string;
  }

  const getCardStatus = async (): Promise<CardStatus> => {
    const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
      method: 'GET',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    });

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('User has not ordered a card');
      }
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### Success Response

<ResponseField name="id" type="string">
  Unique identifier for the card
</ResponseField>

<ResponseField name="holderName" type="string">
  Cardholder name as it appears on the card (uppercase)
</ResponseField>

<ResponseField name="expiryDate" type="string">
  Card expiry date in `YYYY/MM` format
</ResponseField>

<ResponseField name="panLast4" type="string">
  Last 4 digits of the card PAN (Primary Account Number)
</ResponseField>

<ResponseField name="status" type="string">
  Current card status

  **Possible Values:**

  * `ACTIVE` - Card is active and can be used for transactions
  * `FROZEN` - Card is temporarily frozen by the user
  * `BLOCKED` - Card is permanently blocked (requires replacement)
</ResponseField>

<ResponseField name="type" type="string">
  Type of card

  **Possible Values:**

  * `VIRTUAL` - Digital card for online/mobile payments
  * `PHYSICAL` - Physical plastic card
  * `METAL` - Premium metal card
</ResponseField>

<ResponseField name="orderedAt" type="string">
  ISO 8601 timestamp when the card was ordered
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "000000000050277836",
    "holderName": "JOHN DOE",
    "expiryDate": "2028/01",
    "panLast4": "1234",
    "status": "ACTIVE",
    "type": "VIRTUAL",
    "orderedAt": "2023-03-27T17:07:12.662Z"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 - Unauthorized theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "message": "Card not found"
  }
  ```

  ```json 498 - Invalid Client Key theme={null}
  {
    "message": "Invalid client key"
  }
  ```

  ```json 499 - Missing Client Key theme={null}
  {
    "message": "Missing client key"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Card Status Explained

<AccordionGroup>
  <Accordion title="ACTIVE Status">
    **Meaning:** Card is fully functional and can process transactions

    **User Actions Available:**

    * Make purchases online and in-store
    * View card details and PIN
    * Freeze the card temporarily
    * View transaction history

    **Next Steps:** User can begin using the card for payments
  </Accordion>

  <Accordion title="FROZEN Status">
    **Meaning:** Card is temporarily disabled by the user

    **Transaction Behavior:** All transaction attempts will be declined

    **User Actions Available:**

    * Unfreeze the card to restore functionality
    * View card details (but cannot use for purchases)
    * View transaction history

    **Common Use Cases:**

    * Suspected fraudulent activity
    * Lost card (temporary measure before reporting)
    * User wants to temporarily prevent spending

    **Recovery:** Call `POST /v1/card/unfreeze` to restore card to ACTIVE status
  </Accordion>

  <Accordion title="BLOCKED Status">
    **Meaning:** Card is permanently disabled and cannot be reactivated

    **Transaction Behavior:** All transaction attempts will be declined

    **User Actions Available:**

    * View historical transaction data only
    * Order a replacement card

    **Common Causes:**

    * Card reported as lost or stolen
    * Security concerns or fraud detected
    * Card compromised
    * Multiple failed PIN attempts

    **Recovery:** Cannot unfreeze a BLOCKED card. User must order a new card via `POST /v1/card/order`
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Check if User Has a Card

```typescript theme={null}
async function userHasCard(): Promise<boolean> {
  try {
    const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': `Bearer ${accessToken}`
      }
    });

    return response.status === 200;
  } catch (error) {
    return false;
  }
}
```

### Display Card Summary

```typescript theme={null}
async function displayCardSummary() {
  const card = await getCardStatus();

  return {
    lastFour: card.panLast4,
    expiry: card.expiryDate,
    status: card.status,
    canTransact: card.status === 'ACTIVE',
    holderName: card.holderName
  };
}
```

### Monitor Card After Ordering

```typescript theme={null}
async function pollCardStatus(maxAttempts = 10, delayMs = 2000) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const card = await getCardStatus();

      if (card.status === 'ACTIVE') {
        console.log('Card is now active!');
        return card;
      }

      await new Promise(resolve => setTimeout(resolve, delayMs));
    } catch (error) {
      if (i === maxAttempts - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  throw new Error('Card activation timeout');
}
```

### Check if Card Can Process Transactions

```typescript theme={null}
async function canProcessTransactions(): Promise<boolean> {
  try {
    const card = await getCardStatus();
    return card.status === 'ACTIVE';
  } catch (error) {
    return false;
  }
}
```

## Edge Cases and Important Notes

<Warning>
  **404 Not Found Response**

  A `404` error means the user has not ordered a card yet. Handle this gracefully by prompting the user to order a card via `POST /v1/card/order`.
</Warning>

<Note>
  **Security Best Practice**

  This endpoint intentionally returns only the last 4 digits of the PAN. Never attempt to reconstruct or store the full card number. Use `POST /v1/card/details/token` to securely display full card details in a PCI-compliant hosted environment.
</Note>

<Info>
  **Polling Frequency**

  If polling for card status after ordering, use exponential backoff or a reasonable delay (2-5 seconds) between requests to avoid rate limiting.
</Info>

## Implementation Best Practices

### Error Handling

```typescript theme={null}
async function getCardStatusSafely() {
  try {
    const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': `Bearer ${accessToken}`
      }
    });

    if (response.status === 404) {
      return { hasCard: false, card: null };
    }

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }

    const card = await response.json();
    return { hasCard: true, card };
  } catch (error) {
    console.error('Error fetching card status:', error);
    throw error;
  }
}
```

### UI Display Logic

```typescript theme={null}
function getCardStatusColor(status: string): string {
  switch (status) {
    case 'ACTIVE':
      return 'green';
    case 'FROZEN':
      return 'orange';
    case 'BLOCKED':
      return 'red';
    default:
      return 'gray';
  }
}

function getCardStatusMessage(status: string): string {
  switch (status) {
    case 'ACTIVE':
      return 'Your card is active and ready to use';
    case 'FROZEN':
      return 'Your card is temporarily frozen. Unfreeze it to use.';
    case 'BLOCKED':
      return 'Your card is blocked. Please order a replacement.';
    default:
      return 'Unknown card status';
  }
}
```

## Related Endpoints

* `POST /v1/card/order` - Order a new card
* `POST /v1/card/details/token` - Generate token to view sensitive card details
* `POST /v1/card/freeze` - Temporarily freeze the card
* `POST /v1/card/unfreeze` - Unfreeze a frozen card
* `GET /v1/card/transactions` - View card transaction history
* `POST /v1/card/pin/token` - Generate token to view card PIN