Virtual Card Creation
With the Create Virtual Card API, you can create virtual cards that your customers can use instantly once they have been created/issued and funded.
Create a card holder
To successfully create a virtual card, you must first create a card holder, the user to whom the card will be issued. A card holder can request and manage more than one virtual card.
To create a card holder, make a POST request to the endpoint:
{{baseurl}}/api/v1/card-holders
These are the parameters of the request body:
Field | Data Type | Description |
---|---|---|
first_name | String | Required. The first name on the card |
last_name | String | Required. The last name on the card |
email | String | Required. The email of the card holder |
phone | String | Optional. The card holder's phone number |
address | Object | Required. |
address.street | String | Required. The street address of the card holder |
address.city | String | Required. The city address of the card holder |
address.state | String | Required. The state address of the card holder |
address.country | String | Required. The country address of the card holder |
This is what a typical response would look like:
{
"status": true,
"message": "Card holder created successfully",
"data": {
"reference": "Card-Ref-0101111",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "2348012345678",
"address": {
"street": "No 10, John street",
"city": "Lekki",
"state": "Lagos",
"country": "NG"
}
}
}
Create a virtual card (via API)
Once you have created a card holder, you will be able to issue virtual cards for that card holder. These virtual cards must be associated with a Visa or MasterCard scheme.
Always ensure that you have sufficient funds in your issuing balance for card creation.
Use this request to create cards:
{{baseurl}}/api/v1/cards
The request body should have the following parameters:
Field | Data Type | Description |
---|---|---|
amount | Number | Required. This is the amount with which you want to fund the card upon creation. |
currency | String | Required. This is the currency under which the card is created. (USD ) |
card_holder_reference | String | Required. This is the unique reference of the cardholder. |
reference | String | Required. This is your unique reference for the card. |
type | String | Required. This is the type of card to be created. Can be physical or virtual . However, only virtual cards can be issued for now. |
billing | Object | Required. |
billing.address1 | String | Required. This is the billing address' line 1. |
billing.address2 | String | Required. This is the billing address' line 2. |
billing.city | String | Required. This is the billing address' city. |
billing.state | String | Required. This is the billing address' state. |
billing.country | String | Required. This is the billing address' country. |
billing.zip_code | String | Required. This is the zip code of the billing address. |
With a successful request, this is an example of what the card creation response would look like:
{
"status": true,
"message": "Card created successfully",
"data": {
"reference": "CD-S2FegL6YLHt3lUozXH5tRBRH6b6t595bVa1pj",
"merchant_reference": "226eeb6f-f6cb-562f-a5e8-48d91decyth",
"currency": "USD",
"type": "virtual",
"status": "active",
"billing": {
"address1": "No 10, John street",
"address2": "John boulevard",
"city": "John Island",
"state": "LA",
"country": "NG",
"zip_code": "102404"
},
"holder_name": "John Doe",
"pan": "1111113523075881",
"cvv": "022",
"expiry": "2025-04-30T23:59:59.000Z",
"brand": "mastercard",
"first_six": "111111",
"last_four": "5881"
}
}
A webhook notification will also be sent to your application immediately the virtual card is created. The webhook notification request will look like this:
{
"event": "card.creation.success",
"data": {
"reference": "webhook unique reference",
"card_reference": "876eeb6f-f6cb-562f-a5e8-48d91dec7999",
"date": "2000-11-11T10:00:00",
"currency": "USD",
"type": "virtual",
"status": "active",
"billing": {
"address1": "No 14, John street",
"address2": "John boulevard",
"city": "Lekki",
"state": "LA",
"country": "NG",
"zip_code": "102408"
},
"holder_name": "John Doe",
"expiry": "2026-02-28T23:59:59",
"brand": "visa",
"first_six": "111111",
"last_four": "6777"
}
}
merchant_reference
is passed by the merchant when a card is being created. This may be used by the merchant to query the card in case of timeouts.
Virtual card details
Once you have successfully created a virtual card, you can retrieve the details of the card.
The request to get the details of a virtual card is:
{{baseurl}}/api/v1/cards/:reference
And the response would look like this:
{
"status": true,
"message": "Card details retrieved successfully",
"data": {
"reference": "Card-Ref-0000-0011",
"merchant_reference": "John-Doe-Ref",
"type": "virtual",
"first_six": "111111",
"last_four": "6714",
"brand": "visa",
"expiry": "2023-04-06T00:00:00.000Z",
"expiry_month": "04",
"expiry_year": "2023",
"currency": "USD",
"balance": 0,
"status": "active",
"billing": {
"city": "Dr Doe City",
"state": "LA",
"country": "NG",
"address1": "No 78, doe street",
"address2": "doe boulevard",
"zip_code": "102408"
},
"card_holder": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "2348012345678",
"address": {
"city": "Lekki",
"state": "Lagos",
"street": "No 14, Doe street",
"country": "NG"
}
},
"date_created": "2023-04-06T15:33:54.000Z"
}
}
Fetching all cards
You can retrieve all the virtual cards you have created by making a GET request to the following endpoint via API:
{{baseurl}}/api/v1/cards
The API also accepts request parameters. For instance, {{baseurl}}/api/v1/cards?status=active
retrieves all active cards that you have created.
Parameter | Type | Required? | Description |
---|---|---|---|
status | String | false | This is the status of the virtual card. It can be any one of active , terminated , pending , deactivated , or expired . |
start_date | String | false | This is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD. |
end_date | String | false | This is the specific end date for the search query. The expected date format is YYYY-MM-DD. |
See below an example of a response for this request:
{
"status": true,
"message": "Cards retrieved successfully",
"data": {
"data": [
{
"reference": "cd-rf—John-doe",
"type": "virtual",
"currency": "USD",
"first_six": "111111",
"last_four": "6714",
"status": "active",
"holder_name": "John Doe",
"brand": "visa",
"expiry": "2026-03-31T23:59:59.000Z",
"date_created": "2023-04-06T15:33:54.000Z"
},
],
"paging": {
"total_items": 1,
"page_size": 10,
"current": 1,
"count": 1
}
}
}
You can view and manage all the virtual cards you have created from your Kora dashboard. Additionally, you can see the details of a specific card.
To view all the cards you have created, go to the Issuing page and navigate to the Issued Cards tab. Clicking on a card will display its details.

On the card details page, you can view the card transactions, balance, and events.

Updated 4 months ago