> ## 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.

# Card Operations Overview

> Comprehensive guide to managing physical and virtual cards, PIN operations, and transactions

## Introduction

The Card API provides complete control over the card lifecycle, from ordering and activation through day-to-day management and transaction monitoring. Built with security as a priority, all sensitive operations use tokenized access patterns to ensure PCI compliance without exposing card data to your application.

<CardGroup cols={2}>
  <Card title="Order Cards" icon="credit-card" href="/guides/card/ordering">
    Order virtual cards instantly for your verified users
  </Card>

  <Card title="Manage Cards" icon="toggle-on" href="/guides/card/management">
    Freeze, unfreeze, and control card status
  </Card>

  <Card title="PIN Operations" icon="lock" href="/guides/card/pin-operations">
    Secure PIN management with tokenized access
  </Card>

  <Card title="Transactions" icon="receipt" href="/guides/card/transactions">
    View transaction history and generate statements
  </Card>
</CardGroup>

## Card Types

### Virtual Cards

Virtual cards are issued instantly upon order completion and can be used immediately for online purchases and digital wallet integration.

**Characteristics:**

* Instant issuance (no physical delivery required)
* Immediate activation after order
* Full card details available through secure token flow
* Supports all online and digital wallet transactions

**Use Cases:**

* E-commerce purchases
* Subscription services
* Digital wallet integration (Apple Pay, Google Pay)
* Instant account funding

### Physical Cards

<Note>Physical card support is coming soon. Currently, only virtual cards are available.</Note>

Physical cards will provide all the benefits of virtual cards with the addition of in-person purchase capabilities.

**Planned Features:**

* Contactless payments (NFC)
* ATM withdrawals
* In-store purchases
* Same security features as virtual cards

## Card Lifecycle

Understanding the card lifecycle helps you build robust card management features:

```mermaid theme={null}
graph LR
    A[No Card] --> B[Ordered]
    B --> C[Active]
    C --> D[Frozen]
    D --> C
    C --> E[Blocked]
    E --> F[Replaced]
    F --> C
```

### Card States

<AccordionGroup>
  <Accordion title="Active" icon="check-circle">
    Card is fully operational and can be used for transactions. This is the normal operating state after a card is successfully ordered and activated.

    **Available Actions:**

    * Make purchases
    * View card details
    * View/set PIN
    * Freeze card
    * View transactions
  </Accordion>

  <Accordion title="Frozen" icon="snowflake">
    Card is temporarily disabled. All transaction attempts will be declined until the card is unfrozen. User initiated freeze for security purposes.

    **Available Actions:**

    * Unfreeze card
    * View card details (read-only)
    * View transactions

    **Blocked Actions:**

    * Make purchases
    * Change PIN
  </Accordion>

  <Accordion title="Blocked" icon="ban">
    Card is permanently disabled, typically due to fraud detection, repeated failed PIN attempts, or compliance issues. Cannot be unfrozen.

    **Available Actions:**

    * View transaction history
    * Order replacement card

    **Blocked Actions:**

    * All card operations
    * Make purchases
  </Accordion>
</AccordionGroup>

## Security Architecture

### Token-Based Access Model

All sensitive card operations (viewing details, PIN management) use a secure token-based flow:

1. **Generate Token**: Request a single-use token from the API
2. **Use Token**: Present token to hosted secure page or embed in iframe
3. **Token Expires**: Token is invalidated after use or timeout (\~10 minutes)

**Benefits:**

* Sensitive data never touches your application
* PCI compliance without scope expansion
* Reduced security liability
* Built-in session management

<Warning>
  Never attempt to store or cache sensitive card data (PAN, CVV, PIN) in your application. Always use the token-based flow for each access.
</Warning>

### Secure Display Methods

The API uses different methods to securely display sensitive card data:

**Image-Based Display** (Card Details & PIN Viewing)

* Card details (PAN, CVV, expiry) delivered as secure images
* PIN numbers displayed as secure images
* No sensitive data touches your application
* Simple implementation with `<img>` tags
* Customizable styling to match your brand

**Hosted Pages** (PIN Setting Only)

* Interactive PIN entry form
* Built-in validation and error handling
* Embeddable in iframe with postMessage communication
* PCI-compliant PIN submission

<Tabs>
  <Tab title="Image Display (Viewing)">
    ```javascript theme={null}
    // Generate token for card details or PIN viewing
    const response = await fetch('/v1/card/details/token', {
      method: 'POST',
      headers: {
        'X-Client-ID': clientId,
        'Authorization': `Bearer ${accessToken}`
      },
      body: JSON.stringify({
        customCss: {
          cardBackgroundColor: '#000000',
          cardTextColor: '#FFFFFF'
        }
      })
    });

    const { imageUrl } = await response.json();

    // Display as image
    const img = document.createElement('img');
    img.src = imageUrl;
    img.alt = 'Card Details';
    document.getElementById('container').appendChild(img);
    ```
  </Tab>

  <Tab title="Hosted Page (Setting PIN)">
    ```html theme={null}
    <!-- Embed PIN setting page in your application -->
    <iframe
      src="https://cards.baanx.com/pin-direct/set?token={token}"
      sandbox="allow-scripts allow-same-origin allow-forms"
      style="width: 100%; height: 450px; border: none;"
    />
    ```

    **PostMessage Events:**

    * `abort`: User dismissed the page
    * `success`: Operation completed successfully
    * `error`: Operation failed
  </Tab>
</Tabs>

## Available Operations

### Card Information

* **Check Status**: Get current card state and basic details
* **View Details**: Access full card number, CVV, expiry through secure token
* **Transaction History**: Query past transactions with filtering

### Card Control

* **Order Card**: Create new virtual card for verified users
* **Freeze Card**: Temporarily disable card for security
* **Unfreeze Card**: Reactivate frozen card
* **Replace Card**: Order replacement for blocked/lost cards (coming soon)

### PIN Management

* **View PIN**: Display current PIN as secure image
* **Set PIN**: Create or change PIN through secure hosted page
* **Validate PIN**: Verify PIN without exposing it (internal validation)

### Transactions

* **List Transactions**: Retrieve paginated transaction history
* **Filter Transactions**: By date range, merchant, or category
* **Generate Statements**: Export transactions as CSV or PDF

## Prerequisites

Before using card operations, ensure:

<Steps>
  <Step title="User Registration & Consent">
    User must have completed registration including consent acceptance. During registration, users agree to terms of service and provide consent for data processing. See [Consent Management](/guides/consent/overview) for tracking requirements.
  </Step>

  <Step title="User Verification">
    User must have completed KYC and have `VERIFIED` status. Check user status with `GET /v1/user/profile`.
  </Step>

  <Step title="Authentication">
    All card endpoints require both `clientId` and `bearerAuth` (user access token).
  </Step>

  <Step title="No Existing Card">
    Users can only have one active card at a time. Check with `GET /v1/card/status` before ordering.
  </Step>

  <Step title="Funded Wallet">
    Ensure user has delegated wallet with sufficient balance for card operations.
  </Step>
</Steps>

## Common Workflows

### First-Time Card Setup

```javascript theme={null}
// 1. Verify user eligibility
const profile = await fetch('/v1/user/profile', {
  headers: {
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  }
});

if (profile.status !== 'VERIFIED') {
  throw new Error('User must complete KYC first');
}

// 2. Check if user already has a card
const statusResponse = await fetch('/v1/card/status', {
  headers: {
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  }
});

if (statusResponse.ok) {
  console.log('User already has a card');
  return;
}

// 3. Order virtual card
const order = await fetch('/v1/card/order', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({ type: 'VIRTUAL' })
});

// 4. Wait for activation (usually instant for virtual)
const card = await fetch('/v1/card/status', {
  headers: {
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  }
});

console.log(`Card ${card.id} is ${card.status}`);
```

### Temporary Card Freeze (Lost Wallet)

```javascript theme={null}
// User reports wallet lost - freeze card immediately
const freezeResponse = await fetch('/v1/card/freeze', {
  method: 'POST',
  headers: {
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  }
});

if (freezeResponse.ok) {
  console.log('Card frozen - all transactions will be declined');
}

// Later: User finds wallet - unfreeze card
const unfreezeResponse = await fetch('/v1/card/unfreeze', {
  method: 'POST',
  headers: {
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  }
});

if (unfreezeResponse.ok) {
  console.log('Card reactivated');
}
```

### View Card Details Securely

```javascript theme={null}
// 1. Generate token for viewing card details
const tokenResponse = await fetch('https://dev.api.baanx.com/v1/card/details/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-ID': clientId,
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    customCss: {
      cardBackgroundColor: '#000000',
      cardTextColor: '#FFFFFF',
      panBackgroundColor: '#EFEFEF',
      panTextColor: '#000000'
    }
  })
});

const { token, imageUrl } = await tokenResponse.json();

// 2. Display as secure image
const img = document.createElement('img');
img.src = imageUrl;
img.alt = 'Card Details';
img.style.cssText = 'max-width: 100%; border-radius: 12px;';
document.getElementById('card-details-container').appendChild(img);

// 3. Clean up when user closes
function closeCardDetails() {
  img.remove();
  // imageUrl is automatically garbage collected
}
```

## Error Handling

### Common Error Scenarios

<AccordionGroup>
  <Accordion title="404 - Card Not Found">
    User hasn't ordered a card yet. Direct them to the card ordering flow.

    ```javascript theme={null}
    if (response.status === 404) {
      // Show "Order Card" UI
      redirectToCardOrdering();
    }
    ```
  </Accordion>

  <Accordion title="400 - User Already Has Card">
    Returned when attempting to order a card but user already has one.

    ```javascript theme={null}
    {
      "message": "User already has a card",
      "code": "CARD_EXISTS"
    }
    ```

    Fetch existing card status instead of ordering new one.
  </Accordion>

  <Accordion title="403 - User Not Verified">
    User hasn't completed KYC. They must verify identity before ordering cards.

    ```javascript theme={null}
    if (response.status === 403) {
      // Redirect to KYC flow
      redirectToVerification();
    }
    ```
  </Accordion>

  <Accordion title="400 - Invalid Card State">
    Operation not allowed in current card state (e.g., trying to unfreeze an active card).

    ```javascript theme={null}
    {
      "message": "Card is not frozen",
      "code": "INVALID_STATE"
    }
    ```

    Check card status before operations.
  </Accordion>
</AccordionGroup>

## Best Practices

### Security

<Check>Always use HTTPS for all API calls</Check>
<Check>Never log or store sensitive card data</Check>
<Check>Implement token expiration handling</Check>
<Check>Use CSP headers when embedding hosted pages</Check>
<Check>Validate user authentication before card operations</Check>

### User Experience

<Check>Show clear status indicators for card state</Check>
<Check>Provide transaction history for transparency</Check>
<Check>Allow easy freeze/unfreeze for security</Check>
<Check>Display last 4 digits for card identification</Check>
<Check>Offer statement downloads for record keeping</Check>

### Performance

<Check>Cache card status locally with reasonable TTL</Check>
<Check>Use pagination for transaction history</Check>
<Check>Implement optimistic UI updates for freeze/unfreeze</Check>
<Check>Lazy load transaction details on demand</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Order Your First Card" icon="play" href="/guides/card/ordering">
    Learn how to order virtual cards for your users
  </Card>

  <Card title="Implement PIN Security" icon="shield" href="/guides/card/pin-operations">
    Set up secure PIN management flows
  </Card>

  <Card title="Display Transactions" icon="chart-line" href="/guides/card/transactions">
    Build transaction history and statements
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/card/order">
    Explore complete API documentation
  </Card>
</CardGroup>