Skip to main content
POST
/
v1
/
card
/
unfreeze
{
  "success": true
}

​
Overview

Reactivates a frozen card, restoring full functionality and allowing transaction authorizations to resume. This endpoint reverses the freeze action, changing the card status from FROZEN back to ACTIVE.
Immediate RestorationUnfreezing a card takes effect immediately. The card can be used for transactions within seconds of successful unfreezing.

​
When to Use

Issue Resolved

Suspicious activity has been investigated and resolved

Card Found

Previously misplaced card has been located

Resume Spending

User wants to enable the card after voluntary freeze

Subscription Payment

Need to unfreeze before recurring payment date

​
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/unfreeze \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
Success Response

​
success
boolean
Indicates whether the card was successfully unfrozenValue: Always true on successful unfreeze
{
  "success": true
}

​
Error Responses

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

​
What Happens When a Card is Unfrozen?

1

Status Change

The card status changes from FROZEN to ACTIVE immediately
2

Transaction Authorization

The card can now authorize transactions including:
  • Point-of-sale purchases (online and in-store)
  • ATM withdrawals
  • Recurring subscription payments
  • Pre-authorized transactions
3

Immediate Availability

Transactions can be processed within seconds. Payment processors typically recognize the status change within 1-2 seconds.

​
Common Error Scenarios

Error: 400 Bad RequestMessage: "Card is not frozen"Cause: Attempting to unfreeze a card that is already ACTIVE or BLOCKEDSolution: Check card status first using GET /v1/card/status before attempting to unfreeze
Error: 400 Bad RequestCause: Card has BLOCKED status (permanently disabled)Solution: Blocked cards cannot be unfrozen. User must order a new card via POST /v1/card/order
Error: 401 UnauthorizedCause: Missing or invalid Bearer tokenSolution: Ensure valid access token is included in Authorization header

​
Use Case Examples

​
Card Found After Loss

async function handleCardFound() {
  try {
    await unfreezeCard();

    console.log('Card unfrozen and ready to use');

    notifyUser({
      title: 'Card Active',
      message: 'Your card has been unfrozen and is ready for transactions.'
    });

    await refreshCardStatus();
  } catch (error) {
    console.error('Failed to unfreeze card:', error);
    showError('Unable to unfreeze card. Please try again or contact support.');
  }
}

​
Scheduled Unfreeze Before Subscription

async function prepareForSubscriptionPayment(subscriptionDate: Date) {
  const now = new Date();
  const hoursUntilPayment = (subscriptionDate.getTime() - now.getTime()) / (1000 * 60 * 60);

  if (hoursUntilPayment <= 24) {
    const card = await getCardStatus();

    if (card.status === 'FROZEN') {
      await unfreezeCard();

      console.log('Card unfrozen for upcoming subscription payment');

      notifyUser({
        title: 'Card Unfrozen',
        message: `Your card has been unfrozen for your subscription payment scheduled for ${subscriptionDate.toLocaleDateString()}`
      });
    }
  }
}

​
Safe Unfreeze with Status Check

async function unfreezeCardSafely() {
  try {
    const card = await getCardStatus();

    if (card.status === 'ACTIVE') {
      console.log('Card is already active');
      return { success: true, alreadyActive: true };
    }

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

    if (card.status === 'FROZEN') {
      await unfreezeCard();
      return { success: true, alreadyActive: false };
    }

    throw new Error(`Unknown card status: ${card.status}`);
  } catch (error) {
    console.error('Failed to unfreeze card:', error);
    throw error;
  }
}

​
Best Practices

​
User Confirmation

async function promptCardUnfreeze() {
  const confirmed = await showConfirmDialog({
    title: 'Unfreeze Card?',
    message: 'Your card will be activated and ready for transactions immediately.',
    confirmText: 'Unfreeze Card',
    cancelText: 'Keep Frozen'
  });

  if (confirmed) {
    try {
      await unfreezeCard();
      showSuccessMessage('Card is now active');

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

​
Status Verification

async function unfreezeAndVerify() {
  await unfreezeCard();

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

  const card = await getCardStatus();

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

  return card;
}

​
UI State Management

function CardControls({ cardStatus }: { cardStatus: CardStatus }) {
  const [isUnfreezing, setIsUnfreezing] = useState(false);

  const handleUnfreeze = async () => {
    setIsUnfreezing(true);
    try {
      await unfreezeCard();
      onStatusChange('ACTIVE');
    } catch (error) {
      console.error('Unfreeze failed:', error);
      showError('Failed to unfreeze card');
    } finally {
      setIsUnfreezing(false);
    }
  };

  return (
    <button
      onClick={handleUnfreeze}
      disabled={isUnfreezing || cardStatus === 'ACTIVE' || cardStatus === 'BLOCKED'}
    >
      {isUnfreezing ? 'Unfreezing...' : 'Unfreeze Card'}
    </button>
  );
}

​
Freeze/Unfreeze Toggle Component

function CardFreezeToggle() {
  const [card, setCard] = useState<CardStatus | null>(null);
  const [isProcessing, setIsProcessing] = useState(false);

  useEffect(() => {
    loadCardStatus();
  }, []);

  const loadCardStatus = async () => {
    const status = await getCardStatus();
    setCard(status);
  };

  const toggleFreeze = async () => {
    if (!card) return;

    setIsProcessing(true);
    try {
      if (card.status === 'ACTIVE') {
        await freezeCard();
        setCard({ ...card, status: 'FROZEN' });
      } else if (card.status === 'FROZEN') {
        await unfreezeCard();
        setCard({ ...card, status: 'ACTIVE' });
      }
    } catch (error) {
      console.error('Toggle freeze failed:', error);
      showError('Operation failed. Please try again.');
    } finally {
      setIsProcessing(false);
    }
  };

  if (!card) return <div>Loading...</div>;

  if (card.status === 'BLOCKED') {
    return <div>Card is blocked. Order a new card.</div>;
  }

  return (
    <div>
      <p>Status: {card.status}</p>
      <button onClick={toggleFreeze} disabled={isProcessing}>
        {isProcessing
          ? 'Processing...'
          : card.status === 'ACTIVE'
          ? 'Freeze Card'
          : 'Unfreeze Card'}
      </button>
    </div>
  );
}

​
Testing

​
Sandbox Testing

describe('Card Unfreeze Flow', () => {
  it('should unfreeze frozen card', async () => {
    await freezeCard();

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

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

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

  it('should allow transactions after unfreeze', async () => {
    await freezeCard();
    await unfreezeCard();

    const transaction = await attemptTransaction({ amount: 10.00 });
    expect(transaction.status).toBe('CONFIRMED');
  });

  it('should fail to unfreeze already active card', async () => {
    const card = await getCardStatus();
    expect(card.status).toBe('ACTIVE');

    await expect(unfreezeCard()).rejects.toThrow('Card is not frozen');
  });
});

​
Important Notes

Cannot Unfreeze BLOCKED CardsCards with BLOCKED status are permanently disabled and cannot be unfrozen. These cards require replacement via POST /v1/card/order.
Real-Time EffectCard unfreezing takes effect immediately. Payment processors recognize the status change within 1-2 seconds, allowing near-instant transaction processing.
IdempotencyCalling this endpoint on an already active card will return a 400 Bad Request error. Check card status first if unsure of the current state.
  • POST /v1/card/freeze - Freeze an active card to prevent transactions
  • GET /v1/card/status - Check current card status
  • GET /v1/card/transactions - View transaction history
  • POST /v1/card/order - Order a replacement card (for blocked cards)