Get Card Status

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.example.com/v1/card/status', 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/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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/status"

	req, _ := http.NewRequest("GET", 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/status")

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

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

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

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

GET

card

status

Get Card Status

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.example.com/v1/card/status', 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/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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/status"

	req, _ := http.NewRequest("GET", 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/status")

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

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

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

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

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

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

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

import requests

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

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

interface CardStatus {
  id: string;
  holderName: string;
  expiryDate: string;
  panLast4: string;
  status: 'ACTIVE' | 'FROZEN' | 'BLOCKED';
  type: 'VIRTUAL' | 'PHYSICAL' | 'METAL';
  orderedAt: string;
}

const getCardStatus = async (): Promise<CardStatus> => {
  const response = await fetch('https://dev.api.baanx.com/v1/card/status', {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  if (!response.ok) {
    if (response.status === 404) {
      throw new Error('User has not ordered a card');
    }
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
};

Response

Success Response

string

Unique identifier for the card

string

Cardholder name as it appears on the card (uppercase)

string

Card expiry date in YYYY/MM format

string

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

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)

string

Type of cardPossible Values:

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

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

{
  "message": "Not authorized"
}

{
  "message": "Card not found"
}

{
  "message": "Invalid client key"
}

{
  "message": "Missing client key"
}

{
  "message": "Internal server error"
}

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

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Get Card Status

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

​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