Skip to main content

​
Card Management Guide

This guide covers everything you need to know about managing debit and credit cards in your Open Banking application, from card issuance to transaction monitoring.

​
Overview

Card management functionality is essential for modern banking applications. Our API supports comprehensive card operations that allow you to issue, manage, and monitor debit and credit cards for your customers. This functionality enables you to provide complete card services within your application.

​
Key Card Management Operations

​
1. Get Customer Cards

Retrieve all cards belonging to a customer, providing comprehensive information about their card portfolio. 
curl -X GET ${API_BASE_URL}/cards \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "00",
  "message": "Cards retrieved successfully",
  "data": {
    "cards": [
      {
        "card_id": "1",
        "customer_id": "1",
        "product_id": "1",
        "account_number": "1234567890",
        "card_scheme": "VISA",
        "card_type": "VIRTUAL",
        "card_mode": "DEBIT",
        "card_status": "ACTIVE",
        "card_currency": "NGN",
        "card_holder_name": "John Doe",
        "card_number": "1234",
        "card_cvv2": "123",
        "card_default_pin": "1234",
        "card_token": "1234567890",
        "card_expiry": {
          "month": "01",
          "year": "2024"
        },
        "card_address": {
          "street": "123 Main St",
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
        "custom_properties": [
          {
            "id": "card_purpose",
            "description": "Card purpose",
            "type": "string",
            "value": "Online Shopping"
          }
        ]
      }
    ]
  }
}

​
2. Create Customer Card

Create a new card for a customer with specified parameters and configurations. 
curl -X POST ${API_BASE_URL}/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "product_id": "1",
    "card_type": "VIRTUAL",
    "card_mode": "DEBIT",
    "card_status": "ACTIVE",
    "card_currency": "NGN",
    "card_holder_name": "John Doe",
    "card_default_pin": "1234",
    "card_expiry": {
      "month": "01",
      "year": "2024"
    },
    "card_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "custom_properties": [
      {
        "id": "card_purpose",
        "description": "Card purpose",
        "type": "string",
        "value": "Online Shopping"
      }
    ]
  }'

{
  "status": "00",
  "message": "Card created successfully",
  "data": {
    "card_id": "1",
    "customer_id": "1",
    "product_id": "1",
    "account_number": "1234567890",
    "card_scheme": "VISA",
    "card_type": "VIRTUAL",
    "card_mode": "DEBIT",
    "card_status": "ACTIVE",
    "card_currency": "NGN",
    "card_holder_name": "John Doe",
    "card_number": "1234",
    "card_cvv2": "123",
    "card_default_pin": "1234",
    "card_token": "1234567890",
    "card_expiry": {
      "month": "01",
      "year": "2024"
    },
    "card_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "custom_properties": [
      {
        "id": "card_purpose",
        "description": "Card purpose",
        "type": "string",
        "value": "Online Shopping"
      }
    ]
  }
}

​
3. Update Card Status

Update the status of an existing card to modify its operational state. 
curl -X PATCH ${API_BASE_URL}/cards/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "card_status": "BLOCKED",
    "card_holder_name": "John Doe Updated",
    "card_default_pin": "5678",
    "card_expiry": {
      "month": "01",
      "year": "2024"
    },
    "card_address": {
      "street": "456 Updated St",
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "custom_properties": [
      {
        "id": "card_purpose",
        "description": "Updated card purpose",
        "type": "string",
        "value": "Travel Expenses"
      }
    ]
  }'

{
  "status": "00",
  "message": "Card updated successfully",
  "data": {
    "card_id": "1",
    "card_status": "BLOCKED",
    "card_holder_name": "John Doe Updated",
    "account_number": "1234567890",
    "card_default_pin": "5678",
    "card_expiry": {
      "month": "01",
      "year": "2024"
    },
    "card_address": {
      "street": "456 Updated St",
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "custom_properties": [
      {
        "id": "card_purpose",
        "description": "Updated card purpose",
        "type": "string",
        "value": "Travel Expenses"
      }
    ]
  }
}
Make sure you send the appropriate scopes while requesting for a token: cards.list, cards.create, and cards.update. Failure to include these scopes will prevent access to the card management APIs.

​
Card Types and Features

​
Card Types

Our system supports various card types to meet different customer needs:
  • Physical Cards: Physical EMV cards delivered to customer address. Please make sure the card address field are supplied, so that your card can be delviered to this address.
  • Virtual Cards: Digital-only cards for online transactions

​
Card Modes

Cards can have different modes:
  • DEBIT: Card linked to your bank account. You need to have funds in your account before you can spend from it.
  • CREDIT: Card with a pre-approved credit limit. You can spend up to the credit limit and pay back the amount later, typically with interest charges on outstanding balances.
  • PREPAID: Card loaded with a specific amount of money. You can only spend the amount that has been pre-loaded onto the card, providing controlled spending without linking to a bank account.
  • OTHER: Card with specialized functionality or custom features that don’t fit into the standard debit, credit, or prepaid categories.

​
Card Statuses

Cards can have different operational statuses:
  • ACTIVE: Card is fully operational and can be used for transactions
  • INACTIVE: Card is issued but not yet activated
  • BLOCKED: Card is temporarily blocked due to security concerns
  • SUSPENDED: Card is suspended due to policy violations
  • EXPIRED: Card has reached its expiry date

​
Next Steps

Now that you understand card management operations, explore these related topics:
Always implement proper security measures and authentication for card management operations. Ensure compliance with card industry standards and maintain comprehensive audit trails for all card-related activities. Regular monitoring of card usage patterns and proper error handling are essential for successful card management operations.