Cards API

This is the Cards API that provides programmatic access to various resources and services. The API supports the following areas: Card Management. All endpoints require authentication using a Bearer token.

The cards model

The cards model contains all the information about your cards entities.

Properties

Name
cards
Type
array
Description
List of cards items
Name
pagination
Type
object
Description
Object containing pagination data

List Cards

Fetches a list of all cards linked to a user's account.

Request

GET

/v1/cards

curl -G https://api.adiba.app/v1/cards \
  -H "Authorization: Bearer {token}"

{
"cards": [
    {
        "cardId": "CARD_001",
        "cardNumber": "**** **** **** 1234",
        "cardType": "DEBIT",
        "cardBrand": "VISA",
        "cardStatus": "ACTIVE",
        "expiryDate": "12/25",
        "isDefault": true,
        "linkedAccount": "ACC_001",
        "dailyLimit": 500000,
        "monthlyLimit": 5000000
    },
    {
        "cardId": "CARD_002",
        "cardNumber": "**** **** **** 5678",
        "cardType": "CREDIT",
        "cardBrand": "MASTERCARD",
        "cardStatus": "ACTIVE",
        "expiryDate": "06/26",
        "isDefault": false,
        "linkedAccount": "ACC_002",
        "dailyLimit": 1000000,
        "monthlyLimit": 10000000
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 2,
    "hasNext": false,
    "hasPrevious": false
}
}

Read Card

Retrieves detailed information for a specific linked card.

Required attributes

Name
cardId
Type
string
Description
Unique identifier specified in the URL path

Request

GET

/v1/cards/{cardId}

curl -G https://api.adiba.app/v1/cards/{cardId} \
  -H "Authorization: Bearer {token}"

{
"cardId": "CARD_001",
"cardNumber": "**** **** **** 1234",
"cardType": "DEBIT",
"cardBrand": "VISA",
"cardStatus": "ACTIVE",
"expiryDate": "12/25",
"cvv": "***",
"isDefault": true,
"linkedAccount": "ACC_001",
"dailyLimit": 500000,
"monthlyLimit": 5000000,
"currentBalance": 150000,
"availableBalance": 150000,
"lastTransactionDate": "2024-12-01T09:30:00Z",
"cardHolderName": "John Doe",
"issuingBank": "Digital Bank",
"cardFeatures": [
    "CONTACTLESS",
    "ONLINE_PAYMENTS",
    "ATM_WITHDRAWALS"
]
}

Remove Card

Unlinks and removes a card from a user's account.

Required attributes

Name
cardId
Type
string
Description
Unique identifier specified in the URL path

Request

DELETE

/v1/cards/{cardId}

curl -X DELETE https://api.adiba.app/v1/cards/{cardId} \
  -H "Authorization: Bearer {token}" \
  -d '{
"example": "data"
}'

{
"status": "SUCCESS",
"cardId": "CARD_001",
"removedAt": "2024-12-01T11:00:00Z",
"message": "Card removed successfully"
}

(de)Hotlist Card

Blocks a card from being used or unblocks a previously blocked card.

Required attributes

Name
cardId
Type
string
Description
Unique identifier specified in the URL path

Request

POST

/v1/cards/{cardId}/hotlist

curl -X POST https://api.adiba.app/v1/cards/{cardId}/hotlist \
  -H "Authorization: Bearer {token}" \
  -d '{
"action": "BLOCK",
"reason": "Lost card",
"temporary": true,
"duration": "24 hours"
}'

{
"status": "SUCCESS",
"cardId": "CARD_001",
"action": "BLOCK",
"cardStatus": "BLOCKED",
"processedAt": "2024-12-01T11:15:00Z",
"message": "Card blocked successfully",
"unblockDate": "2024-12-02T11:15:00Z"
}

Add External Card

Links a new debit or credit card to the user's account.

Request

POST

/v1/cards/external

curl -X POST https://api.adiba.app/v1/cards/external \
  -H "Authorization: Bearer {token}" \
  -d '{
"cardNumber": "4111111111111111",
"expiryDate": "12/25",
"cvv": "123",
"cardHolderName": "John Doe",
"cardType": "DEBIT",
"cardBrand": "VISA",
"issuingBank": "External Bank",
"isDefault": false
}'

{
"status": "SUCCESS",
"cardId": "CARD_003",
"cardNumber": "**** **** **** 1111",
"cardType": "DEBIT",
"cardBrand": "VISA",
"cardStatus": "ACTIVE",
"expiryDate": "12/25",
"isDefault": false,
"linkedAt": "2024-12-01T11:30:00Z",
"message": "External card added successfully"
}

Request a New Card

Initiates a request for a new physical or virtual card.

Request

POST

/v1/cards/internal

curl -X POST https://api.adiba.app/v1/cards/internal \
  -H "Authorization: Bearer {token}" \
  -d '{
"cardType": "PHYSICAL",
"cardBrand": "VISA",
"linkedAccount": "ACC_001",
"cardHolderName": "John Doe",
"deliveryAddress": {
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "100001",
    "country": "Nigeria"
},
"isDefault": false,
"dailyLimit": 500000,
"monthlyLimit": 5000000
}'

{
"status": "SUCCESS",
"requestId": "REQ_001_20241201_001",
"cardId": "CARD_004",
"cardType": "PHYSICAL",
"cardBrand": "VISA",
"cardStatus": "PENDING",
"estimatedDeliveryDate": "2024-12-08T00:00:00Z",
"requestedAt": "2024-12-01T11:45:00Z",
"message": "Card request submitted successfully. Physical card will be delivered within 5-7 business days."
}