Unfreeze Card

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

import requests

url = "https://api.example.com/v1/card/unfreeze"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/card/unfreeze', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/card/unfreeze",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/card/unfreeze"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/card/unfreeze")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "success": true
}

POST

card

unfreeze

Unfreeze Card

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

import requests

url = "https://api.example.com/v1/card/unfreeze"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/card/unfreeze', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/card/unfreeze",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/card/unfreeze"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/card/unfreeze")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

string

required

Your public API client key

boolean

default:false

Set to true to route requests to the US backend environment

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"

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

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

import requests

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

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

interface UnfreezeCardResponse {
  success: boolean;
}

const unfreezeCard = async (): Promise<UnfreezeCardResponse> => {
  const response = await fetch('https://dev.api.baanx.com/v1/card/unfreeze', {
    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();
};

Response

Success Response

boolean

Indicates whether the card was successfully unfrozenValue: Always true on successful unfreeze

{
  "success": true
}

Error Responses

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

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "Card not found"
}

{
  "message": "Invalid client key"
}

{
  "message": "Missing client key"
}

{
  "message": "Internal server error"
}

What Happens When a Card is Unfrozen?

Status Change

The card status changes from FROZEN to ACTIVE immediately

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

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

Cannot Unfreeze BLOCKED Card

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

Missing Authentication

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)

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Unfreeze Card

Overview

When to Use

Issue Resolved

Card Found

Resume Spending

Subscription Payment

Authentication

Request

Headers

Request Example

Response

Success Response

Error Responses

What Happens When a Card is Unfrozen?

Common Error Scenarios

Use Case Examples

Card Found After Loss

Scheduled Unfreeze Before Subscription

Safe Unfreeze with Status Check

Best Practices

User Confirmation

Status Verification

UI State Management

Freeze/Unfreeze Toggle Component

Testing

Sandbox Testing

Important Notes

​Overview

​When to Use

Issue Resolved

Card Found

Resume Spending

Subscription Payment

​Authentication

​Request

​Headers

​Request Example

​Response

​Success Response

​Error Responses

​What Happens When a Card is Unfrozen?

​Common Error Scenarios

​Use Case Examples

​Card Found After Loss

​Scheduled Unfreeze Before Subscription

​Safe Unfreeze with Status Check

​Best Practices

​User Confirmation

​Status Verification

​UI State Management

​Freeze/Unfreeze Toggle Component

​Testing

​Sandbox Testing

​Important Notes

​Related Endpoints

Overview

When to Use

Authentication

Request

Headers

Request Example

Response

Success Response

Error Responses

What Happens When a Card is Unfrozen?

Common Error Scenarios

Use Case Examples

Card Found After Loss

Scheduled Unfreeze Before Subscription

Safe Unfreeze with Status Check

Best Practices

User Confirmation

Status Verification

UI State Management

Freeze/Unfreeze Toggle Component

Testing

Sandbox Testing

Important Notes

Related Endpoints