Virtual Card Creation

A virtual card is a card aimed at online transactions.
It has its very own card design, PAN, CVV and Expiration date.

A virtual card should be displayed as an image to the cardholder.

Prerequisite

Before being able to create a Virtual card, you must have :

  • A Valitaded Enduser with a ledger.
    The Ledger doesn't need to be upgraded.
    This Ledger will be debited at each transaction.
  • A Card Program matching the Enduser type and the Ledger type, and allowing Virtual Cards.
    See Card Programs page for more details.

Creating the card

Virtual Cards can be created either by a Partner, or directly by the Enduser himself.

To create a Virtual Card, use the "Create a Card" endpoint and provide the Ledger Id as well as the Card Program.
You could also provide extra informations :

  • friendlyName : A custom name you want to give to this card.

deliveryMethod and nameOnCard are not relevant for Virtual cards

Request Body format :

Request Body schema: application/json
Any of:
deliveryMethod
required
string
Enum: "UK_MAIL" "INTERNATIONAL_MAIL" "DHL"
ledgerId
required
string <uuid>
profileId
required
string <uuid>

The card profile id. Must be an active card profile.

nameOnCard
string^[A-Z\s]{1,21}$
Default: "FIRSTNAME LASTNAME"

The name that will be printed on the card. Can only contain ISO basic Latin alphabet and can be up to 21 characters long including spaces.

friendlyName
string [ 0 .. 255 ] characters
Array of objects

You can add rules when creating a card. You can only send one rule by type in the list.

As a partner, this rules take priority over the rules set in the profile

application/json
{
  • "deliveryMethod": "UK_MAIL",
  • "ledgerId": "a2873d47-59a8-4daf-a325-cb2c04557dd7",
  • "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",
  • "nameOnCard": "FIRSTNAME LASTNAME",
  • "friendlyName": "string",
  • "rules": [
    ]
}
A successful Card creation will return a unique id :
Copy
Copied
{
  "id": "120e9d1f-8444-4b91-85e8-5b208615a3e5",
}

When created, a Virtual card is activated as soon as created.

Fetch the card

You can now Fetch the card by the id to get all its information :
id
required
string <uuid>
endUserId
required
string <uuid>
ledgerId
required
string <uuid>
required
object (Profile)
expiryDate
string
nameOnCard
string
friendlyName
string
object (AddressResponseDto)

Address used on the bank statements of your users.

deliveryMethod
string
Enum: "UK_MAIL" "INTERNATIONAL_MAIL" "DHL" "COURIER"
truncatedPan
string

Last 4 digits of the card. The truncated pan is only displayed if the card has been activated.

type
required
string
Enum: "PHYSICAL" "VIRTUAL"
scheme
required
string
Enum: "MASTERCARD" "VISA"
currency
required
string
Enum: "EUR" "GBP" "USD" "PLN" "AUD" "CHF" "CAD" "SEK" "NOK" "JPY" "HUF" "HKD" "NZD" "CZK" "SGD" "RON" "HRK"
required
object (CardStatusDto)
creationDate
required
string <date-time>
updateDate
required
string <date-time>
pinStatus
required
string
Enum: "LOCKED" "UNLOCKED" "WAITING_ONLINE_TRANSACTION"
required
Array of objects (CardRuleResponseDto)

Card status

Cards can have mutliples status during life cycle :

Card statusDescription
CREATEDThe card have been created
REACTIVATINGThe card is currently reactivating after being suspended (few seconds)
ACTIVEThe card is active and ready to use
SUSPENDINGThe card us curretly suspending, cannot be used
SUSPENDEDThe card is suspended and cannot be used
CLOSINGThe card is currently closing, cannot be used
CLOSEDThe card is permanantly closed
FAILEDThe card creation failed, please check your payload or contact customer care
INTERNAL_ERRORNot your fault, please contact your customer care, check our status page
EXPIREDThe card is expired, you can renew it.

You can close / suspend a card for multiple reasons :

Status reasonDescription
STOLENThe card is closed / suspended because has been stolen
LOSTThe card is closed / suspended because has been lost
DAMAGEDThe card is closed / suspended because has been damaged
OTHERAny other reason, you need to add a otherStatusReason

The operator is the one which has decided to close / suspend the card. It can be you as a Partner, an Enduser request or us.