Skip to main content
POST
/
v1
/
card
/
freeze
{
  "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 ActionFrozen 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 -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 frozenValue: Always true on successful freeze
{
  "success": true
}

​
Error Responses

{
  "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 CardsCalling 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 CardsCards with BLOCKED status cannot be frozen or unfrozen. Blocked cards are permanently disabled and require replacement via POST /v1/card/order.
Subscription PaymentsFreezing 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 EffectCard 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;
  }
}
  • 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)