Unfreeze Card

Reactivate a frozen card to resume transaction authorizations

POST /v1/card/unfreeze

Unfreeze Card

cURL

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

200 - Success

{
  "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 Restoration

Unfreezing 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

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 unfrozen

Value: Always true on successful unfreeze

200 - Success

{
  "success": true
}

Error Responses

400 - Bad Request

{
  "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

Card Not Frozen

Error: 400 Bad Request

Message: "Card is not frozen"

Cause: Attempting to unfreeze a card that is already ACTIVE or BLOCKED

Solution: Check card status first using GET /v1/card/status before attempting to unfreeze

Cannot Unfreeze BLOCKED Card

Error: 400 Bad Request

Cause: Card has BLOCKED status (permanently disabled)

Solution: Blocked cards cannot be unfrozen. User must order a new card via POST /v1/card/order

Missing Authentication

Error: 401 Unauthorized

Cause: Missing or invalid Bearer token

Solution: 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 Cards

Cards with BLOCKED status are permanently disabled and cannot be unfrozen. These cards require replacement via POST /v1/card/order.

Real-Time Effect

Card unfreezing takes effect immediately. Payment processors recognize the status change within 1-2 seconds, allowing near-instant transaction processing.

Idempotency

Calling this endpoint on an already active card will return a 400 Bad Request error. Check card status first if unsure of the current state.

Related Endpoints

• 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)