> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Management

> Learn how to manage debit and credit cards for your customers

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

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET ${API_BASE_URL}/cards \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "signature: ${SIGNATURE}"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

### 2. Create Customer Card

Create a new card for a customer with specified parameters and configurations.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    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"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

### 3. Update Card Status

Update the status of an existing card to modify its operational state.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    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"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

<Note>
  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.
</Note>

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

* [Developer Onboarding](/guides/developer-onboarding) - Onboard Developer
* [Customer Management](/guides/customers) - Manage customer information and relationships
* [Account Management](/guides/account) - Manage bank accounts and balances
* [Transfers](/guides/transfers) - Process money transfers between accounts
* [Bill Payment](/guides/bill-payment) - Process utility and bill payments
* [Direct Debit Management](/guides/direct-debit) - Manage Payment Cards
* [Dispute Management](/guides/dispute-management) - Manage Payment Cards
* [Savings Information](/guides/savings-information) - Manage Payment Cards
* [Loan Information](/guides/loans) - Access customer Loan Information

<Button href="/api-reference/payments" size="sm">
  Explore Card Management APIs
</Button>

<Note>
  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.
</Note>