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

# Card Issuance

> Issue physical and virtual debit cards to customers, manage their lifecycle, and handle PIN operations.

TagPay's card issuance system lets you issue debit cards to your customers, link them to their wallets, and manage the full card lifecycle — from issuance through blocking, unblocking, and PIN changes.

<Warning>
  All card endpoints are protected by a **card access guard**. Your merchant account must have at least one card product enabled before you can call these endpoints. Contact your account manager to enable card issuance on your account.
</Warning>

***

## Issue a card

Use `POST /card/issue` to issue a new card to a customer. This creates a card record and links it to the customer's wallet.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/card/issue \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "accountNumber": "1234567890"
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "cardId": "card_xyz789",
    "customerId": "cus_abc123",
    "accountNumber": "1234567890",
    "status": "inactive",
    "maskedPan": "****1234",
    "issuedAt": "2026-04-08T10:00:00.000Z"
  }
}
```

<Note>
  Newly issued cards have a status of `inactive`. Customers must activate their card before it can be used for transactions.
</Note>

***

## Activate a card

After a card is issued, the customer activates it using `POST /card/activate`. Activation typically requires the card's account number.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/card/activate \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "1234567890"
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "cardId": "card_xyz789",
    "status": "active",
    "activatedAt": "2026-04-08T10:05:00.000Z"
  }
}
```

***

## List cards for a wallet

Retrieve all cards associated with a customer's wallet using `GET /card/wallet/cards`.

```bash cURL theme={null}
curl -X GET "https://api.tagpay.ng/v1/card/wallet/cards?accountNumber=1234567890" \
  -H "Authorization: Bearer <your-token>"
```

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "cardId": "card_xyz789",
      "maskedPan": "****1234",
      "status": "active",
      "linkedAccountNumber": "1234567890",
      "issuedAt": "2026-04-08T10:00:00.000Z"
    }
  ]
}
```

You can also look up a specific card by account number using `GET /card/by-account`:

```bash cURL theme={null}
curl -X GET "https://api.tagpay.ng/v1/card/by-account?accountNumber=1234567890" \
  -H "Authorization: Bearer <your-token>"
```

***

## Block a card

If a card is reported lost, stolen, or involved in fraud, block it immediately using `POST /card/block`. A blocked card cannot be used for any transactions.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/card/block \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "1234567890"
  }'
```

***

## Unblock a card

To restore access to a previously blocked card, call `POST /card/unblock`.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/card/unblock \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "1234567890"
  }'
```

***

## PIN management

### Reset and change PIN

Use `POST /card/reset-and-change-pin` to reset a customer's card PIN. This is typically used when a customer forgets their PIN or requests a PIN change through your support channel.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/card/reset-and-change-pin \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "1234567890",
    "newPin": "5678"
  }'
```

<Warning>
  PIN operations are sensitive. Ensure your integration enforces proper authorization — for example, requiring the customer to authenticate before allowing a PIN reset.
</Warning>

***

## Bulk card production

For large-scale card issuance, TagPay supports a multi-step bulk production workflow.

<Steps>
  <Step title="Prepare card data">
    Submit a data preparation request to initiate the bulk issuance batch:

    ```bash cURL theme={null}
    curl -X POST https://api.tagpay.ng/v1/card/data-prep \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "accounts": ["1234567890", "0987654321"]
      }'
    ```
  </Step>

  <Step title="Check data prep status">
    Poll `GET /card/data-prep` to monitor the preparation job. Once complete, the prepared card data is ready for production.

    ```bash cURL theme={null}
    curl -X GET "https://api.tagpay.ng/v1/card/data-prep?batchId=batch_001" \
      -H "Authorization: Bearer <your-token>"
    ```
  </Step>

  <Step title="Submit for bulk production">
    Once the data prep job is complete, trigger bulk card production:

    ```bash cURL theme={null}
    curl -X POST https://api.tagpay.ng/v1/card/bulk-production \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "batchId": "batch_001"
      }'
    ```
  </Step>

  <Step title="Retry failed items (if needed)">
    If any cards in the batch fail during production, retry them using:

    ```bash cURL theme={null}
    curl -X POST https://api.tagpay.ng/v1/card/bulk-production/retry \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "batchId": "batch_001"
      }'
    ```
  </Step>
</Steps>

***

## Card linking and unlinking

You can manually link an existing card to a wallet or unlink it:

<CodeGroup>
  ```bash Link card theme={null}
  curl -X POST https://api.tagpay.ng/v1/card/link \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{
      "accountNumber": "1234567890",
      "cardId": "card_xyz789"
    }'
  ```

  ```bash Unlink card theme={null}
  curl -X POST https://api.tagpay.ng/v1/card/unlink \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{
      "accountNumber": "1234567890",
      "cardId": "card_xyz789"
    }'
  ```
</CodeGroup>