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.