Cards Details

Retrieving card data, status management (block/unblock), PIN changes and channel controls.

Get Cards

GET /v1/api/cards/get-cards

Fetch a paginated list of cards for a business. Supports server-side filtering via searchParams.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
pageNumber	Yes	Path	Number	The page of results to retrieve
pageSize	Yes	Path	Number	The number of items that should be returned per page
searchParams	Yes	Path	Object	Optional filters

Sample Request

curl --location '{BASE_URL}/v1/api/integration/get-cards' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --body '{
    "pageNumber": 1,
    "pageSize": 100,
    "searchParams": {
        // "cardStatus" : "ACTIVATED"
        // "accountNumber": "",
        // "cardRequestId": "",
        //"cardHolderName" : "PHYLLIS"
    }
}'

Sample Response (200 - OK)

{
    "totalCount": 3,
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": [
        {
            "cardRequestId": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
            "accountNumber": "9000003642",
            "cardType": "Physical",
            "pan": "ioFI/vC+ZrZI2V6Nsm9sSZBHRrriEp3o8bThDSvkjhg=",
            "maskPan": "506136******3284",
            "cardHolderName": "VICTOR NWOGU",
            "cardExpirationDate": "2030-11-30T00:00:00Z",
            "isActivated": true,
            "enableAtm": true,
            "enablePos": true,
            "enableWeb": true,
            "enableContactless": false,
            "cardStatus": "ACTIVATED",
            "pin": null,
            "cvv": null,
            "cvv2": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "isDeleted": false,
            "id": "954fbf91-e641-43a9-8000-3195de6f134d",
            "creationDate": "2025-11-28T13:17:52.44887Z",
            "lastUpdateDate": "2025-11-28T13:17:52.447953Z",
            "timeStamp": null
        },
        {
            "cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
            "accountNumber": "9000002975",
            "cardType": "Physical",
            "pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
            "maskPan": "506136******3292",
            "cardHolderName": "VICTOR NWOGU",
            "cardExpirationDate": "2030-11-30T00:00:00Z",
            "isActivated": false,
            "enableAtm": true,
            "enablePos": true,
            "enableWeb": true,
            "enableContactless": false,
            "cardStatus": "ACTIVATED",
            "pin": null,
            "cvv": null,
            "cvv2": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "isDeleted": false,
            "id": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
            "creationDate": "2025-11-28T12:59:44.469499Z",
            "lastUpdateDate": "2025-11-28T12:59:44.469212Z",
            "timeStamp": null
        },
        {
            "cardRequestId": "210a612d-64e2-4988-8156-73de27f174cb",
            "accountNumber": "9000003673",
            "cardType": "Physical",
            "pan": "GcxmFJRAeiZ1hRqVIGL7BA3dgdFAp4EAkTdICHt5AwY=",
            "maskPan": "506136******3300",
            "cardHolderName": "VICTOR NWOGU",
            "cardExpirationDate": "2030-11-30T00:00:00Z",
            "isActivated": false,
            "enableAtm": true,
            "enablePos": true,
            "enableWeb": true,
            "enableContactless": false,
            "cardStatus": "ACTIVATED",
            "pin": null,
            "cvv": null,
            "cvv2": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "isDeleted": false,
            "id": "843b75b0-a124-4542-912a-90012ef805cf",
            "creationDate": "2025-11-28T12:45:59.074021Z",
            "lastUpdateDate": "2025-11-28T12:45:59.072525Z",
            "timeStamp": null
        }
    ]
}

Sample Response (404 - Not Found)

{
    "totalCount": 0,
    "status": false,
    "message": "No record found for search",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Get Single Card Details

GET /v1/api/cards/get-card-by-id/:cardAccountId

This endpoint is used to retrieve a single card details by ID.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
cardAccountId	Yes	Path	String	The unique identifier for the card

Sample Request

curl --location '{BASE_URL}/v1/api/cards/get-card-by-id/{cardAccountId}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": {
        "cardAccounts": {
            "cardRequestId": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
            "accountNumber": "9000003642",
            "cardType": "Physical",
            "pan": "DOCpG6KHYWUqEr5OyMcAPpGhYt0Go22ORFt8Uoj2Prg=",
            "maskPan": "506136******3284",
            "cardHolderName": "VICTOR NWOGU",
            "cardExpirationDate": "2030-11-30T00:00:00Z",
            "isActivated": true,
            "enableAtm": true,
            "enablePos": true,
            "enableWeb": true,
            "enableContactless": false,
            "cardStatus": "ACTIVATED",
            "pin": null,
            "cvv": null,
            "cvv2": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "isDeleted": false,
            "id": "954fbf91-e641-43a9-8000-3195de6f134d",
            "creationDate": "2025-11-28T13:17:52.44887Z",
            "lastUpdateDate": "2025-11-28T13:17:52.447953Z",
            "timeStamp": null
        },
        "cardRequest": {
            "pickUpLocation": "PICKUP",
            "phoneNumber": "08077766651",
            "email": "[email protected]",
            "gender": "Male",
            "batchNumber": null,
            "houseNumber": "70",
            "streetName": "Lekki Court",
            "lga": "Eti-Osa",
            "landMark": "Lekki",
            "state": "Lagos",
            "cardType": "Physical",
            "deliveryFee": 0,
            "issuanceFee": 0,
            "totalAmount": 0,
            "requestStatus": "READY",
            "instrumentNumber": null,
            "referenceNo": null,
            "transactionMessage": null,
            "safeTokenBatchNumber": null,
            "safeTokenStatus": null,
            "deliveryBatchNumber": null,
            "deliveryStatus": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "transactionStatusCode": null,
            "pickUpDate": null,
            "exportedDate": null,
            "uploadedDate": null,
            "id": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
            "creationDate": "2025-11-28T13:17:52.447274Z",
            "lastUpdateDate": "2025-11-28T13:17:52.447761Z",
            "isDeleted": false,
            "timeStamp": null
        },
        "cardTransactions": [],
        "cardRequestHistory": [
            {
                "cardRequestId": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
                "message": "Card request initiated and card pan generated.",
                "id": "75c116ae-5c87-452b-bd95-00ec9c6644f7",
                "creationDate": "2025-11-28T13:17:52.449162Z",
                "lastUpdateDate": null,
                "isDeleted": false,
                "timeStamp": null
            }
        ]
    }
}

Sample Response (404 - Not Found)

{
    "status": false,
    "message": "No record found for search",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Get Card By Account Number

GET /v1/api/cards/get-card-by-account-number/{accountNumber}

This endpoint is used to retrieve a single card details by account number.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
accountNumber	Yes	Path	String	The account number for the card(s)

Sample Request

curl --location '{BASE_URL}/v1/api/cards/get-card-by-account-number/{accountNumber}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": [
        {
            "cardRequestId": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
            "accountNumber": "9000003642",
            "cardType": "Physical",
            "pan": "DOCpG6KHYWUqEr5OyMcAPpGhYt0Go22ORFt8Uoj2Prg=",
            "maskPan": "506136******3284",
            "cardHolderName": "VICTOR NWOGU",
            "cardExpirationDate": "2030-11-30T00:00:00Z",
            "isActivated": true,
            "enableAtm": true,
            "enablePos": true,
            "enableWeb": true,
            "enableContactless": false,
            "cardStatus": "ACTIVATED",
            "pin": null,
            "cvv": null,
            "cvv2": null,
            "businessId": "79331544-6a66-4fb4-8633-ebdaea4790ea",
            "isDeleted": false,
            "id": "954fbf91-e641-43a9-8000-3195de6f134d",
            "creationDate": "2025-11-28T13:17:52.44887Z",
            "lastUpdateDate": "2025-11-28T13:17:52.447953Z",
            "timeStamp": null
        }
    ]
}

Sample Response (400 - Not Found)

{
    "status": false,
    "message": "No record found for search",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Block Card

POST /v1/api/cards/block-card

This is used to block a card

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
CardAccountId	Yes	Body	String	The unique identifier for the card being blocked
ReasonForBlocking	Yes	Body	String	Reason for blocking card --- "They should always pass '5' here"

Sample Request

curl --location '{BASE_URL}/v1/api/cards/block-card' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{ "CardAccountId" : "f6abaa64-4921-4094-a4f1-66241b030b01",
    "ReasonForBlocking" : "5"}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": {
        "cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
        "accountNumber": "9000002975",
        "cardType": "Physical",
        "pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
        "maskPan": "506136******3292",
        "cardHolderName": "VICTOR NWOGU",
        "cardExpirationDate": "2030-11-30T00:00:00Z",
        "isActivated": false,
        "enableAtm": true,
        "enablePos": true,
        "enableWeb": true,
        "enableContactless": false,
        "cardStatus": "BLOCKED",
        "pin": null,
        "cvv": null,
        "cvv2": null,
        "businessId": null,
        "isDeleted": false,
        "id": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
        "creationDate": "2025-11-28T12:59:44.469499Z",
        "lastUpdateDate": "2025-12-08T09:55:33.528026Z",
        "timeStamp": null
    }
}

Sample Response (400 - Bad Request)

{
    "status": false,
    "message": "Validation error - CardAccountId is required. | CardAccountId must be a valid GUID.",
    "statusCode": "09",
    "data": null
}

Sample Response (404 - Not Found)

{
    "status": false,
    "message": "No record found",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Unblock Card

POST /v1/api/cards/unblock-card

This is used to unblock a card

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
CardAccountId	Yes	Body	String	The unique identifier for the card being unblocked

Sample Request

curl --location '{BASE_URL}/v1/api/cards/unblock-card' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{ "CardAccountId" : "f6abaa64-4921-4094-a4f1-66241b030b01"}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": {
        "cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
        "accountNumber": "9000002975",
        "cardType": "Physical",
        "pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
        "maskPan": "506136******3292",
        "cardHolderName": "VICTOR NWOGU",
        "cardExpirationDate": "2030-11-30T00:00:00Z",
        "isActivated": false,
        "enableAtm": true,
        "enablePos": true,
        "enableWeb": true,
        "enableContactless": false,
        "cardStatus": "ACTIVATED",
        "pin": null,
        "cvv": null,
        "cvv2": null,
        "businessId": null,
        "isDeleted": false,
        "id": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
        "creationDate": "2025-11-28T12:59:44.469499Z",
        "lastUpdateDate": "2025-12-08T09:58:57.765608Z",
        "timeStamp": null
    }
}

Sample Response (400 - Bad Request)

{
    "status": false,
    "message": "Validation error - CardAccountId is required. | CardAccountId must be a valid GUID.",
    "statusCode": "09",
    "data": null
}

Sample Response (404 - Not Found)

{
    "status": false,
    "message": "No record found",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Manage Card Channels

POST /v1/api/cards/manage-card-channels

This endpoint allows you to manage the channels associated with a specific card account. You can enable or disable various functionalities such as ATM, POS, web, and contactless transactions for the card.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
CardAccountId	Yes	Body	String	The unique identifier for the card account.
EnableAtm	Yes	Body	Boolean	Flag to enable or disable ATM transactions.
EnablePos	Yes	Body	Boolean	Flag to enable or disable POS transactions.
EnableWeb	Yes	Body	Boolean	Flag to enable or disable web transactions.
EnableContactless	Yes	Body	Boolean	Flag to enable or disable contactless transactions.

Sample Request

curl --location '{BASE_URL}/v1/api/cards/manage-card-channels' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{
    "CardAccountId": "5e29acea-5e46-462d-9066-8934e0834c71",
    "EnableAtm": false,
    "EnablePos": false,
    "EnableWeb": false,
    "EnableContactless": false
}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": {
        "cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
        "accountNumber": "9000002975",
        "cardType": "Physical",
        "pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
        "maskPan": "506136******3292",
        "cardHolderName": "VICTOR NWOGU",
        "cardExpirationDate": "2030-11-30T00:00:00Z",
        "isActivated": false,
        "enableAtm": false,
        "enablePos": false,
        "enableWeb": false,
        "enableContactless": false,
        "cardStatus": "ACTIVATED",
        "pin": null,
        "cvv": null,
        "cvv2": null,
        "businessId": null,
        "isDeleted": false,
        "id": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
        "creationDate": "2025-11-28T12:59:44.469499Z",
        "lastUpdateDate": "2025-12-08T11:30:25.697638Z",
        "timeStamp": null
    }
}

Sample Response (404 - Not Found)

{
    "status": false,
    "message": "No record found",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Change Card PIN

POST /v1/api/cards/change-card-pin

This endpoint allows clients to change the PIN of an existing card using the provided card account ID. This is essential for users who wish to update their security credentials for enhanced protection against unauthorized access. The process requires the user to input their new PIN and confirm it to ensure accuracy.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
CardAccountId	Yes	Body	String	The unique identifier for the card account for which the PIN is being changed.
oldPin	Yes	Body	String	The cards old pin.
newPin	Yes	Body	String	The new PIN that the user wants to set for the card. This should be a secure four-digit code.
confirmPin	Yes	Body	String	A confirmation of the new PIN to ensure it matches the entered PIN.

Sample Request

curl --location '{BASE_URL}/v1/api/cards/manage-card-channels' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{
    "cardAccountId": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
    "oldPin" : "1234",
    "newPin": "0000",
    "confirmPin": "0000"
}'

Sample Response (200 - OK)

{
    "status": true,
    "message": "Operation successful",
    "statusCode": "00",
    "data": {
        "cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
        "accountNumber": "9000002975",
        "cardType": "Physical",
        "pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
        "maskPan": "506136******3292",
        "cardHolderName": "VICTOR NWOGU",
        "cardExpirationDate": "2030-11-30T00:00:00Z",
        "isActivated": false,
        "enableAtm": false,
        "enablePos": false,
        "enableWeb": false,
        "enableContactless": false,
        "cardStatus": "ACTIVATED",
        "pin": "enSVxXpKGUlEOALwuxep6g==",
        "cvv": null,
        "cvv2": null,
        "businessId": null,
        "isDeleted": false,
        "id": "3ddb1503-af10-4e7b-8a30-eae7707912f5",
        "creationDate": "2025-11-28T12:59:44.469499Z",
        "lastUpdateDate": "2025-12-08T11:37:45.454463Z",
        "timeStamp": null
    }
}

Sample Response (404 - Not Found)

{
    "status": false,
    "message": "No record found",
    "statusCode": "25",
    "data": null
}

Sample Response (500 - Internal Server Error)

{
    "status": false,
    "message": "An error occurred while processing this request. Kindly refer to the StatusCode.",
    "statusCode": "06",
    "data": null
}

Cards Details

Get Cards​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Get Single Card Details​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Get Card By Account Number​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (400 - Not Found)​

Sample Response (500 - Internal Server Error)​

Block Card​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (400 - Bad Request)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Unblock Card​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (400 - Bad Request)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Manage Card Channels​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Change Card PIN​

Parameters​

Sample Request​

Sample Response (200 - OK)​

Sample Response (404 - Not Found)​

Sample Response (500 - Internal Server Error)​

Get Cards

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)

Get Single Card Details

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)

Get Card By Account Number

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (400 - Not Found)

Sample Response (500 - Internal Server Error)

Block Card

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (400 - Bad Request)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)

Unblock Card

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (400 - Bad Request)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)

Manage Card Channels

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)

Change Card PIN

Parameters

Sample Request

Sample Response (200 - OK)

Sample Response (404 - Not Found)

Sample Response (500 - Internal Server Error)