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:

FieldData TypeDescription
first_nameStringRequired. The first name on the card
last_nameStringRequired. The last name on the card
emailStringRequired. The email of the card holder
phoneStringOptional. The card holder's phone number
addressObjectRequired.
address.streetStringRequired. The street address of the card holder
address.cityStringRequired. The city address of the card holder
address.stateStringRequired. The state address of the card holder
address.countryStringRequired. 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:

FieldData TypeDescription
amountNumberRequired. This is the amount with which you want to fund the card upon creation.
currencyStringRequired. This is the currency under which the card is created. (USD)
card_holder_referenceStringRequired. This is the unique reference of the cardholder.
referenceStringRequired. This is your unique reference for the card.
typeStringRequired. This is the type of card to be created. Can be physical or virtual. However, only virtual cards can be issued for now.
billingObjectRequired.
billing.address1StringRequired. This is the billing address' line 1.
billing.address2StringRequired. This is the billing address' line 2.
billing.cityStringRequired. This is the billing address' city.
billing.stateStringRequired. This is the billing address' state.
billing.countryStringRequired. This is the billing address' country.
billing.zip_codeStringRequired. 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.

ParameterTypeRequired?Description
statusStringfalseThis is the status of the virtual card. It can be any one of active, terminated, pending, deactivated, or expired.
start_dateStringfalseThis is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD.
end_dateStringfalseThis 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.

Issued Cards Page

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

Card Detail page