Freeze Card

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

import requests

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

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/freeze', 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/freeze",
  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/freeze"

	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/freeze")

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

freeze

Freeze Card

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

import requests

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

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/freeze', 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/freeze",
  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/freeze"

	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/freeze")

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

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

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

const response = await fetch('https://dev.api.baanx.com/v1/card/freeze', {
  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/freeze"
headers = {
    "x-client-key": "YOUR_CLIENT_KEY",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

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

interface FreezeCardResponse {
  success: boolean;
}

const freezeCard = async (): Promise<FreezeCardResponse> => {
  const response = await fetch('https://dev.api.baanx.com/v1/card/freeze', {
    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 frozenValue: Always true on successful freeze

{
  "success": true
}

Error Responses

{
  "message": "Card is already 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 Frozen?

Immediate Effect

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

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

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

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)

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Freeze Card

Overview

When to Use

Suspected Fraud

Lost Card

Budget Control

Travel Preparation

Authentication

Request

Headers

Request Example

Response

Success Response

Error Responses

What Happens When a Card is Frozen?

Use Case Examples

Fraud Prevention

Temporary Budget Lock

Lost Card Management

Idempotency

Important Considerations

Best Practices

User Confirmation

Status Verification

UI State Management

Testing

Sandbox Testing

Monitoring and Analytics

​Overview

​When to Use

Suspected Fraud

Lost Card

Budget Control

Travel Preparation

​Authentication

​Request

​Headers

​Request Example

​Response

​Success Response

​Error Responses

​What Happens When a Card is Frozen?

​Use Case Examples

​Fraud Prevention

​Temporary Budget Lock

​Lost Card Management

​Idempotency

​Important Considerations

​Best Practices

​User Confirmation

​Status Verification

​UI State Management

​Testing

​Sandbox Testing

​Monitoring and Analytics

​Related Endpoints

Overview

When to Use

Authentication

Request

Headers

Request Example

Response

Success Response

Error Responses

What Happens When a Card is Frozen?

Use Case Examples

Fraud Prevention

Temporary Budget Lock

Lost Card Management

Idempotency

Important Considerations

Best Practices

User Confirmation

Status Verification

UI State Management

Testing

Sandbox Testing

Monitoring and Analytics

Related Endpoints