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

​
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

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

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