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

# Freeze Card

> Temporarily disable the card to prevent all transaction authorizations

## Overview

Freezes the user's card, temporarily disabling it and preventing all transaction authorizations. This is a reversible action that allows users to quickly secure their card when they suspect suspicious activity or want to temporarily prevent spending.

<Info>
  **Reversible Action**

  Frozen cards can be reactivated at any time using the `POST /v1/card/unfreeze` endpoint. No data is lost, and the same card details remain valid.
</Info>

## When to Use

<CardGroup cols={2}>
  <Card title="Suspected Fraud" icon="shield-halved">
    User suspects unauthorized activity on their card and wants to prevent further transactions
  </Card>

  <Card title="Lost Card" icon="magnifying-glass">
    Card is temporarily misplaced but not confirmed lost or stolen
  </Card>

  <Card title="Budget Control" icon="piggy-bank">
    User wants to temporarily prevent spending without blocking the card permanently
  </Card>

  <Card title="Travel Preparation" icon="plane">
    Freeze card before travel and unfreeze when needed at destination
  </Card>
</CardGroup>

## 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 POST https://dev.api.baanx.com/v1/card/freeze \
    -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/freeze', {
    method: 'POST',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

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

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

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

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

  ```typescript TypeScript theme={null}
  interface FreezeCardResponse {
    success: boolean;
  }

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

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

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

## Response

### Success Response

<ResponseField name="success" type="boolean">
  Indicates whether the card was successfully frozen

  **Value:** Always `true` on successful freeze
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 - Bad Request theme={null}
  {
    "message": "Card is already frozen"
  }
  ```

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

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

  ```json 404 - Card 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>

## What Happens When a Card is Frozen?

<Steps>
  <Step title="Immediate Effect">
    The card status changes from `ACTIVE` to `FROZEN` instantly. All pending and future transaction authorizations will be declined.
  </Step>

  <Step title="Transaction Authorizations">
    Any transaction attempts will be declined with a "card frozen" or similar message. This includes:

    * Point-of-sale purchases (online and in-store)
    * ATM withdrawals
    * Recurring subscription payments
    * Pre-authorized transactions
  </Step>

  <Step title="Historical Data Preserved">
    All transaction history and card details remain intact. Users can still:

    * View transaction history via `GET /v1/card/transactions`
    * View card details via `POST /v1/card/details/token`
    * View card status via `GET /v1/card/status`
  </Step>

  <Step title="Reversible Action">
    The card can be unfrozen at any time using `POST /v1/card/unfreeze`, restoring full functionality immediately.
  </Step>
</Steps>

## Use Case Examples

### Fraud Prevention

```typescript theme={null}
async function reportSuspiciousActivity() {
  try {
    await freezeCard();

    console.log('Card frozen successfully');
    console.log('Contact support to investigate suspicious activity');

    notifyUser({
      title: 'Card Frozen',
      message: 'Your card has been frozen for security. Contact support for assistance.'
    });
  } catch (error) {
    console.error('Failed to freeze card:', error);
  }
}
```

### Temporary Budget Lock

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

  if (card.status === 'ACTIVE') {
    await freezeCard();

    console.log('Spending locked until you unfreeze your card');

    notifyUser({
      title: 'Spending Locked',
      message: 'Your card is now frozen. Unfreeze it anytime to resume spending.'
    });
  }
}
```

### Lost Card Management

```typescript theme={null}
async function handleLostCard(confirmedLost: boolean) {
  if (confirmedLost) {
    await freezeCard();

    console.log('Card frozen. Report as lost/stolen to get a replacement.');

    showDialog({
      title: 'Card Frozen',
      message: 'Do you want to report this card as lost or stolen?',
      actions: [
        { label: 'Report Lost/Stolen', action: () => reportCardLost() },
        { label: 'I Found It', action: () => unfreezeCard() }
      ]
    });
  } else {
    await freezeCard();

    console.log('Card frozen temporarily. You can unfreeze it when found.');
  }
}
```

## Idempotency

<Note>
  **Already Frozen Cards**

  Calling this endpoint on an already frozen card will return a `400 Bad Request` error with the message "Card is already frozen". Check card status first if you're unsure of the current state.
</Note>

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

    if (card.status === 'FROZEN') {
      console.log('Card is already frozen');
      return { success: true, alreadyFrozen: true };
    }

    if (card.status === 'BLOCKED') {
      throw new Error('Card is blocked and cannot be frozen');
    }

    await freezeCard();
    return { success: true, alreadyFrozen: false };
  } catch (error) {
    console.error('Failed to freeze card:', error);
    throw error;
  }
}
```

## Important Considerations

<Warning>
  **Cannot Freeze BLOCKED Cards**

  Cards with `BLOCKED` status cannot be frozen or unfrozen. Blocked cards are permanently disabled and require replacement via `POST /v1/card/order`.
</Warning>

<Info>
  **Subscription Payments**

  Freezing a card will cause recurring subscription payments to fail. Inform users that they should unfreeze their card before scheduled subscription renewals or update payment methods for critical services.
</Info>

<Note>
  **Real-Time Effect**

  Card freezing takes effect immediately. There may be a brief delay (typically \<1 second) for the status change to propagate to payment processors.
</Note>

## Best Practices

### User Confirmation

```typescript theme={null}
async function promptCardFreeze() {
  const confirmed = await showConfirmDialog({
    title: 'Freeze Card?',
    message: 'Your card will be temporarily disabled. All transactions will be declined until you unfreeze it.',
    confirmText: 'Freeze Card',
    cancelText: 'Cancel'
  });

  if (confirmed) {
    try {
      await freezeCard();
      showSuccessMessage('Card frozen successfully');

      await refreshCardStatus();
    } catch (error) {
      showErrorMessage('Failed to freeze card. Please try again.');
    }
  }
}
```

### Status Verification

```typescript theme={null}
async function freezeAndVerify() {
  await freezeCard();

  await new Promise(resolve => setTimeout(resolve, 500));

  const card = await getCardStatus();

  if (card.status !== 'FROZEN') {
    console.warn('Card status is not FROZEN after freeze operation');
    throw new Error('Card freeze verification failed');
  }

  return card;
}
```

### UI State Management

```typescript theme={null}
function CardControls({ cardStatus }: { cardStatus: CardStatus }) {
  const [isFreezing, setIsFreezing] = useState(false);

  const handleFreeze = async () => {
    setIsFreezing(true);
    try {
      await freezeCard();
      onStatusChange('FROZEN');
    } catch (error) {
      console.error('Freeze failed:', error);
      showError('Failed to freeze card');
    } finally {
      setIsFreezing(false);
    }
  };

  return (
    <button
      onClick={handleFreeze}
      disabled={isFreezing || cardStatus === 'FROZEN' || cardStatus === 'BLOCKED'}
    >
      {isFreezing ? 'Freezing...' : 'Freeze Card'}
    </button>
  );
}
```

## Testing

### Sandbox Testing

In sandbox/test environments, you can freeze and unfreeze cards repeatedly to test your integration:

```typescript theme={null}
describe('Card Freeze Flow', () => {
  it('should freeze active card', async () => {
    const statusBefore = await getCardStatus();
    expect(statusBefore.status).toBe('ACTIVE');

    const result = await freezeCard();
    expect(result.success).toBe(true);

    const statusAfter = await getCardStatus();
    expect(statusAfter.status).toBe('FROZEN');
  });

  it('should prevent transactions when frozen', async () => {
    await freezeCard();

    const transaction = await attemptTransaction(amount: 10.00);
    expect(transaction.status).toBe('DECLINED');
    expect(transaction.declineReason).toContain('frozen');
  });

  it('should fail to freeze already frozen card', async () => {
    await freezeCard();

    await expect(freezeCard()).rejects.toThrow('Card is already frozen');
  });
});
```

## Monitoring and Analytics

Consider tracking freeze events for insights:

```typescript theme={null}
async function freezeCardWithAnalytics(reason: string) {
  const startTime = Date.now();

  try {
    await freezeCard();

    analytics.track('Card Frozen', {
      reason,
      duration: Date.now() - startTime,
      timestamp: new Date().toISOString()
    });

    return { success: true };
  } catch (error) {
    analytics.track('Card Freeze Failed', {
      reason,
      error: error.message,
      duration: Date.now() - startTime
    });

    throw error;
  }
}
```

## Related Endpoints

* `POST /v1/card/unfreeze` - Unfreeze a frozen card to restore functionality
* `GET /v1/card/status` - Check current card status
* `GET /v1/card/transactions` - View transaction history (works on frozen cards)
* `POST /v1/card/order` - Order a replacement card (if card is blocked)