Card Requests
Creating and tracking card requests.
Create Card Request
POST /v1/api/cards/create-card-request
This endpoint is used to make a request for 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 |
| virtualAccountNumber | Yes | Body | String | Customer’s virtual account number to associate the card with. Examples: 9000003642, 9000064610 |
| Yes | Body | String | Cardholder email for notifications. | |
| cardHolderName | Yes | Body | String | Full name to be embossed or stored for the card. Example: Victor Onamus |
| gender | Yes | Body | String / Enum | Cardholder gender. Example: Male, Female |
| phoneNumber | Yes | Body | String | Contact number of the card holder |
| houseNumber | Yes | Body | String | Residential House or Flat number. Example: 70. |
| streetName | Yes | Body | String | Street name of residence. Example: Lekki Court. |
| landMark | Yes | Body | String | Nearby landmark for address clarity. Example: Lekki. |
| lga | Yes | Body | String | Local Government Area. Example: Eti-Osa |
| state | Yes | Body | String | State/ Region. Example: Lagos. |
Sample Request
curl --location '{BASE_URL}/v1/api/cards/create-card-request' \--header 'secret: {SECRET_KEY}' \--header 'api-key: {API_KEY}' \--header 'Content-Type: application/json' \--data '{"virtualAccountNumber": "9000003642",
"Email" : "[email protected]",
"cardHolderName": "Victor Nwogu",
"gender" : "Male",
"phoneNumber": "08077766651",
"houseNumber": "70",
"streetName": "Lekki Court",
"landMark": "Lekki",
"lga": "Eti-Osa",
"state": "Lagos"}'
Sample Response (200 - OK)
{
"status": true,
"message": "Operation successful",
"statusCode": "00",
"data": {
"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
},
"cardAccounts": {
"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:00",
"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
},
"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 (400 - Bad Request)
{
"status": false,
"message": "Validation error - Gender is required. | Gender must be either 'Male' or 'Female'.",
"statusCode": "09",
"data": null
}
Sample Response (409 - Conflict)
{
"status": false,
"message": "Your card already exists.",
"statusCode": "26",
"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
}
Sample Response (404 - Not Found)
{
"totalCount": 0,
"status": false,
"message": "No record found for search",
"statusCode": "25",
"data": null
}
Get Card Request
GET /v1/api/cards/get-card-requests
This endpoint is used to retrieve a requests for cards that have been made.
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 | 1-based page index. |
| pageSize | Yes | Path | Number | Number of records per page. |
| searchParams | Yes | Path | Object | Filters. All fields inside are optional.
|
Sample Request
curl --location '{BASE_URL}/v1/api/cards/get-card-requests' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --data '{
"pageNumber": 1,
"pageSize": 10,
"searchParams": {
// "cardRequestId": "6a5793ff-c69c-4c58-b470-e17675471e18"
// "email": "",
// "phoneNumber": "",
// "accountNumber" : "2000054339",
//"cardHolderName" : "Lamidi",
// "startDate" : "2025-06-11",
// "endDate" : "2025-07-11"
}'
Sample Response (200 - OK)
{
"totalCount": 3,
"status": true,
"message": "Operation successful",
"statusCode": "00",
"data": [
{
"accountNumber": "9000003642",
"pan": "ioFI/vC+ZrZI2V6Nsm9sSZBHRrriEp3o8bThDSvkjhg=",
"cardType": "Physical",
"email": "[email protected]",
"cardHolderName": "VICTOR NWOGU",
"pickUpLocation": "PICKUP",
"phoneNumber": "08077766651",
"houseNumber": "70",
"batchNumber": null,
"safeTokenBatchNumber": null,
"deliveryBatchNumber": null,
"streetName": "Lekki Court",
"lga": "Eti-Osa",
"landMark": "Lekki",
"gender": "Male",
"state": "Lagos",
"deliveryFee": 0,
"issuanceFee": 0,
"totalAmount": 0,
"requestStatus": "READY",
"instrumentNumber": null,
"referenceNo": null,
"transactionMessage": null,
"transactionStatusCode": null,
"cardRequestId": "ad9a366e-c505-4d8c-bbf6-c02fb6c2551b",
"creationDate": "2025-11-28T13:17:52.44887Z",
"exportedDate": null,
"cardExpirationDate": "2030-11-30T00:00:00Z"
},
{
"accountNumber": "9000002975",
"pan": "fTD2fGCisvGXploZ/dSuB5bmi1uxJ+9APspFKL5gt/A=",
"cardType": "Physical",
"email": "[email protected]",
"cardHolderName": "VICTOR NWOGU",
"pickUpLocation": "PICKUP",
"phoneNumber": "08077766651",
"houseNumber": "70",
"batchNumber": null,
"safeTokenBatchNumber": null,
"deliveryBatchNumber": null,
"streetName": "Lekki Court",
"lga": "Eti-Osa",
"landMark": "Lekki",
"gender": "Male",
"state": "Lagos",
"deliveryFee": 0,
"issuanceFee": 0,
"totalAmount": 0,
"requestStatus": "READY",
"instrumentNumber": null,
"referenceNo": null,
"transactionMessage": null,
"transactionStatusCode": null,
"cardRequestId": "ff720aa6-9674-43ba-93bb-d62a15b277fb",
"creationDate": "2025-11-28T12:59:44.469499Z",
"exportedDate": null,
"cardExpirationDate": "2030-11-30T00:00:00Z"
},
{
"accountNumber": "9000003673",
"pan": "GcxmFJRAeiZ1hRqVIGL7BA3dgdFAp4EAkTdICHt5AwY=",
"cardType": "Physical",
"email": "[email protected]",
"cardHolderName": "VICTOR NWOGU",
"pickUpLocation": "PICKUP",
"phoneNumber": "08077766651",
"houseNumber": "70",
"batchNumber": null,
"safeTokenBatchNumber": null,
"deliveryBatchNumber": null,
"streetName": "Lekki Court",
"lga": "Eti-Osa",
"landMark": "Lekki",
"gender": "Male",
"state": "Lagos",
"deliveryFee": 0,
"issuanceFee": 0,
"totalAmount": 0,
"requestStatus": "READY",
"instrumentNumber": null,
"referenceNo": null,
"transactionMessage": null,
"transactionStatusCode": null,
"cardRequestId": "210a612d-64e2-4988-8156-73de27f174cb",
"creationDate": "2025-11-28T12:45:59.074021Z",
"exportedDate": null,
"cardExpirationDate": "2030-11-30T00:00:00Z"
}
]
}
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
}
Note
- Dates must be ISO-8601 (YYYY-MM-DD).
- If both startDate and endDate are provided, endDate should be on/after startDate.
- Provide at least one filter when querying production systems to avoid large scans.
- Pagination: pageNumber starts at 1.
Get Single Card Request
GET /v1/api/cards/get-card-requests-by-id/{cardRequestId}
This endpoint is used to retrieve a single card request.
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 |
| cardRequestId | Yes | Path | String | The unique identifier for the card request |
Sample Response
curl --location '{BASE_URL}/v1/api/cards/get-card-requests-by-id/{cardRequestId}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'
Sample Response (200 - OK)
{
"status": true,
"message": "Operation successful",
"statusCode": "00",
"data": {
"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
},
"cardAccounts": {
"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
},
"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
}