Get Card Status - Baanx API

Overview

Retrieves comprehensive information about the authenticated user’s card, including its current status, holder details, expiry date, and card type. This endpoint is essential for checking card availability and displaying card information in your application.

This endpoint returns basic card information only. Sensitive details like the full PAN, CVV, and PIN are never exposed through this endpoint. Use the secure token-based endpoints for accessing sensitive information.

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 GET https://dev.api.baanx.com/v1/card/status \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Success Response

string

Unique identifier for the card

holderName

string

Cardholder name as it appears on the card (uppercase)

expiryDate

string

Card expiry date in YYYY/MM format

panLast4

string

Last 4 digits of the card PAN (Primary Account Number)

status

string

Current card statusPossible Values:

ACTIVE - Card is active and can be used for transactions
FROZEN - Card is temporarily frozen by the user
BLOCKED - Card is permanently blocked (requires replacement)

type

string

Type of cardPossible Values:

VIRTUAL - Digital card for online/mobile payments
PHYSICAL - Physical plastic card
METAL - Premium metal card

orderedAt

string

ISO 8601 timestamp when the card was ordered

{
  "id": "000000000050277836",
  "holderName": "JOHN DOE",
  "expiryDate": "2028/01",
  "panLast4": "1234",
  "status": "ACTIVE",
  "type": "VIRTUAL",
  "orderedAt": "2023-03-27T17:07:12.662Z"
}

Error Responses

{
  "message": "Not authenticated"
}

Card Status Explained

ACTIVE Status

Meaning: Card is fully functional and can process transactionsUser Actions Available:

Make purchases online and in-store
View card details and PIN
Freeze the card temporarily
View transaction history

Next Steps: User can begin using the card for payments

FROZEN Status

Meaning: Card is temporarily disabled by the userTransaction Behavior: All transaction attempts will be declinedUser Actions Available:

Unfreeze the card to restore functionality
View card details (but cannot use for purchases)
View transaction history

Common Use Cases:

Suspected fraudulent activity
Lost card (temporary measure before reporting)
User wants to temporarily prevent spending

Recovery: Call POST /v1/card/unfreeze to restore card to ACTIVE status

BLOCKED Status

Meaning: Card is permanently disabled and cannot be reactivatedTransaction Behavior: All transaction attempts will be declinedUser Actions Available:

View historical transaction data only
Order a replacement card

Common Causes:

Card reported as lost or stolen
Security concerns or fraud detected
Card compromised
Multiple failed PIN attempts

Recovery: Cannot unfreeze a BLOCKED card. User must order a new card via POST /v1/card/order

Common Use Cases

Check if User Has a Card

async function userHasCard(): Promise<boolean> {
  try {
    const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': `Bearer ${accessToken}`
      }
    });

    return response.status === 200;
  } catch (error) {
    return false;
  }
}

Display Card Summary

async function displayCardSummary() {
  const card = await getCardStatus();

  return {
    lastFour: card.panLast4,
    expiry: card.expiryDate,
    status: card.status,
    canTransact: card.status === 'ACTIVE',
    holderName: card.holderName
  };
}

Monitor Card After Ordering

async function pollCardStatus(maxAttempts = 10, delayMs = 2000) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const card = await getCardStatus();

      if (card.status === 'ACTIVE') {
        console.log('Card is now active!');
        return card;
      }

      await new Promise(resolve => setTimeout(resolve, delayMs));
    } catch (error) {
      if (i === maxAttempts - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  throw new Error('Card activation timeout');
}

Check if Card Can Process Transactions

async function canProcessTransactions(): Promise<boolean> {
  try {
    const card = await getCardStatus();
    return card.status === 'ACTIVE';
  } catch (error) {
    return false;
  }
}

Edge Cases and Important Notes

404 Not Found ResponseA 404 error means the user has not ordered a card yet. Handle this gracefully by prompting the user to order a card via POST /v1/card/order.

Security Best PracticeThis endpoint intentionally returns only the last 4 digits of the PAN. Never attempt to reconstruct or store the full card number. Use POST /v1/card/details/token to securely display full card details in a PCI-compliant hosted environment.

Polling FrequencyIf polling for card status after ordering, use exponential backoff or a reasonable delay (2-5 seconds) between requests to avoid rate limiting.

Implementation Best Practices

Error Handling

async function getCardStatusSafely() {
  try {
    const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': `Bearer ${accessToken}`
      }
    });

    if (response.status === 404) {
      return { hasCard: false, card: null };
    }

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }

    const card = await response.json();
    return { hasCard: true, card };
  } catch (error) {
    console.error('Error fetching card status:', error);
    throw error;
  }
}

UI Display Logic

function getCardStatusColor(status: string): string {
  switch (status) {
    case 'ACTIVE':
      return 'green';
    case 'FROZEN':
      return 'orange';
    case 'BLOCKED':
      return 'red';
    default:
      return 'gray';
  }
}

function getCardStatusMessage(status: string): string {
  switch (status) {
    case 'ACTIVE':
      return 'Your card is active and ready to use';
    case 'FROZEN':
      return 'Your card is temporarily frozen. Unfreeze it to use.';
    case 'BLOCKED':
      return 'Your card is blocked. Please order a replacement.';
    default:
      return 'Unknown card status';
  }
}

POST /v1/card/order - Order a new card
POST /v1/card/details/token - Generate token to view sensitive card details
POST /v1/card/freeze - Temporarily freeze the card
POST /v1/card/unfreeze - Unfreeze a frozen card
GET /v1/card/transactions - View card transaction history
POST /v1/card/pin/token - Generate token to view card PIN

​Overview

​Authentication

​Request

​Headers

​Request Example

​Response

​Success Response

​Error Responses

​Card Status Explained

​Common Use Cases

​Check if User Has a Card

​Display Card Summary

​Monitor Card After Ordering

​Check if Card Can Process Transactions

​Edge Cases and Important Notes

​Implementation Best Practices

​Error Handling

​UI Display Logic

​Related Endpoints

Overview

Authentication

Request

Headers

Request Example

Response

Success Response

Error Responses

Card Status Explained

Common Use Cases

Check if User Has a Card

Display Card Summary

Monitor Card After Ordering

Check if Card Can Process Transactions

Edge Cases and Important Notes

Implementation Best Practices

Error Handling

UI Display Logic

Related Endpoints