Card Issuance

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.

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.

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.

cURL

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

Response

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

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

Activate a card

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

cURL

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

Response

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

cURL

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

Response

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

cURL

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.

cURL

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.

cURL

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.

cURL

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

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

Bulk card production

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

Prepare card data

Submit a data preparation request to initiate the bulk issuance batch:

cURL

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

Check data prep status

Poll GET /card/data-prep to monitor the preparation job. Once complete, the prepared card data is ready for production.

cURL

curl -X GET "https://api.tagpay.ng/v1/card/data-prep?batchId=batch_001" \
  -H "Authorization: Bearer <your-token>"

Submit for bulk production

Once the data prep job is complete, trigger bulk card production:

cURL

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

Retry failed items (if needed)

If any cards in the batch fail during production, retry them using:

cURL

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

Card linking and unlinking

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

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

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

Get Started

Core Concepts

Guides

Issue a card

Activate a card

List cards for a wallet

Block a card

Unblock a card

PIN management

Reset and change PIN

Bulk card production

Card linking and unlinking

​Issue a card

​Activate a card

​List cards for a wallet

​Block a card

​Unblock a card

​PIN management

​Reset and change PIN

​Bulk card production

​Card linking and unlinking

Issue a card

Activate a card

List cards for a wallet

Block a card

Unblock a card

PIN management

Reset and change PIN

Bulk card production

Card linking and unlinking