Freeze Card

Temporarily disable the card to prevent all transaction authorizations

POST /v1/card/freeze

Freeze Card

cURL

curl --request POST \
  --url https://api.example.com/v1/card/freeze \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'

200 - Success

{
  "success": true
}

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.

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.

When to Use

Suspected Fraud

User suspects unauthorized activity on their card and wants to prevent further transactions

Lost Card

Card is temporarily misplaced but not confirmed lost or stolen

Budget Control

User wants to temporarily prevent spending without blocking the card permanently

Travel Preparation

Freeze card before travel and unfreeze when needed at destination

Authentication

This endpoint requires authentication via Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request

Headers

x-client-key · string · required

Your public API client key

x-us-env · boolean · default: false

Set to true to route requests to the US backend environment

Authorization · string · required

Bearer token for authentication

Request Example

cURL

curl -X POST https://dev.api.baanx.com/v1/card/freeze \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Success Response

success · boolean

Indicates whether the card was successfully frozen

Value: Always true on successful freeze

200 - Success

{
  "success": true
}

Error Responses

400 - Bad Request

{
  "message": "Card is already frozen"
}

What Happens When a Card is Frozen?

1. Immediate Effect

   The card status changes from ACTIVE to FROZEN instantly. All pending and future transaction authorizations will be declined.

2. 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
3. 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
4. Reversible Action

   The card can be unfrozen at any time using POST /v1/card/unfreeze, restoring full functionality immediately.

Use Case Examples

Fraud Prevention

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

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

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

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.

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

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.

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.

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.

Best Practices

User Confirmation

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

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

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:

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:

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)