Search Overlay

Prepaid Cards



The Cards module exposes features for managing prepaid cards, like create card, update fetching list of the cards.


Service class for managing prepaid card related operations.

Use the following code to obtain an instance of CardService:

const cardService = Wallet.getInstance().getCardService();

Get customer prepaid cards

Retrieve a list of all prepaid cards for the current customer. CardParameters are the parameters for filtering the customer's cards. Use include parameter to add additional information into the response: TOKENIZATIONS - include information about the mobile wallets tokenizations.


Parameter Type Description Example
cardType CardType Optional parameter to filter cards by card type. CardType.VIRTUAL
limit number Optional parameter to limit the number of results. 20
offset number Optional parameter to specify the starting position, where 1 is the first page. 0
status [CardStatus] Optional parameter. List of card statuses which will be returned. Optional parameter, if not set all statuses will be returned. [CardStatus.ACTIVE, CardStatus.CANCELLED]
include [CardIncludesParam] Optional parameter. Include listed properties in the response. [CardIncludesParam.TOKENIZATIONS]


Value Description
TOKENIZATIONS Include additional information in card.


Enum class representing the type of a card.

Value Description
PHYSICAL The card is physical.
VIRTUAL The card is virtual.


Enum class representing the status of a card.

Value Description
ACTIVE The card is currently active and can be used for transactions.
APPLIED The card application is in progress or awaiting approval.
EXPIRED The card has expired and is no longer valid for use.
DIGITAL The card is in a digital format, such as a virtual or electronic card.
PENDING Intermediate status before issuing a card, while performing additional validations.
CANCELLED The card is canceled and can't be used for any kind of operation. The status is (IRREVERSIBLE).
SUSPENDED The status is changed from CS (Customer Service) representative or due to customer actions like (wrong activation info).
LOCKED Card is locked by the customer and can't be used for payments.
ISSUED The status indicates that the customer has successfully applied for a PHYSICAL card, but the card is not yet activated and can't be used for payments.
LOST The PHYSICAL card is lost by the customer. The status is (IRREVERSIBLE) and no payments will be accepted.
DAMAGED The PHYSICAL card is damaged, but it can be used for online payments.


Enum class representing the scheme of a card.

Value Description
MC The card is Mastercard.
VISA The card is Visa.

The response is aCardList object which contains [Card] and PagingResultMeta objects.

  • PagingResultMeta contains information about:
    • numberOfRecords - the total number of records available
    • limit - the maximum number of records per page
    • page - the current page number.
  • Card contains information about the card such as cardId, status, expiry, lastFour, bin, customerId, cardType, programName, currency, mobile,deliveryAddress,createdDate, accountId, scheme,activationDate, isPinSet, externalId, tokenizations
    • tokenizations contains object MobileWalletTokenizationList which contains list of MobileWalletTokenization with information such as dpanRef, walletId, walletType, status


Enum class representing the type of a mobile wallet.

Value Description
APPLE_PAY The wallet type is Apple Pay.
GOOGLE_PAY The wallet type is Google Pay.
SAMSUNG_PAY The wallet type is Samsung Pay.


Enum class representing the tokenization status of a mobile wallet.

Value Description
COMPLETED The tokenization request is completed.
INITIATED The tokenization request is initiated.
const cardParameters: CardParameters = {
    cardType: CardType.VIRTUAL,
    limit: null,
    offset: null,
    status: [CardStatus.ACTIVE, CardStatus.EXPIRED],
    include: [CardIncludesParam.TOKENIZATIONS]

    .then(response => console.log('Cards list', response))
    .catch(error => console.error('Error fetching cards', error));

You can achieve pagination by combining the limit and offset filters. For instance, implementing pagination with a page size of 2 results per page would involve configuring:

  • Page 1: limit=2, offset=0
  • Page 2: limit=2, offset=2
  • Page 3: limit=2, offset=4

Retrieve single prepaid card

Provides detailed information about specific card by cardId. The response is a single card object.

const cardId = 'f16ba382-eb42-481a-b08f-c57bdc9aae24';
const include = [CardIncludesParam.TOKENIZATIONS];

Wallet.getInstance().getCardService().get(cardId, include)
    .then(response => console.log('Card', response))
    .catch(error => console.error('Error fetching card', error));

Create a prepaid card

Create a new Physical or Virtual prepaid card for a customer, based on the provided programName.


Parameter Type Description Example
programName string Required parameter. Program name retrieved from CardService. 'SKRILL-VIRTUAL-MC-EEA'
currency string Required parameter. Currency code in three-letter format ("Alpha-3"). 'EUR'
mobile string Optional parameter. If not provided, we will try to use the mobile phone provided during the customer onboarding. Mobile phone number must be in format "+1 123456789". '+1 123456789'
cardPin string Optional parameter. For EU Customers: The Card pin should be 4 digits. US customers must set their card PIN via a separate REST HTTP call. '1234'
externalId string Optional external identifier in merchant system. 'a2322550-af91-417f-867e-681efad44b9d'
deliveryAddress DeliveryAddress Optional parameter. The DeliveryAddress object will be used for the PHYSICAL card delivery. It can be null in case of VIRTUAL card.
termsAndConditionsAccepted boolean The field must be present for US customers. For other countries it is not required. true
eDisclosureAccepted boolean The field must be present for US customers. For other countries it is not required. true


Parameter Type Description Example
address1 string Required parameter mandatory for address. 'Tsarigradsko Shose 73'
address2 string Optional parameter for address line 2 'Apartment 2C'
address3 string Optional parameter for address line 3. 'Cityville, State 78901'
city string Required parameter for specifying the city. Max 30 characters: letters, spaces, hyphen and period. 'Sofia'
countryCode string Required parameter in ISO-3166 Alpha 2, representing a country code 'BG'
state string Optional parameter. For US Customers: 2,3-character state or province abbreviation. 'NL'
postalCode string Required parameter. For EU customers: maximum length 16. For US customers: Pattern: ^[a-zA-Z0-9-\ ]*$ '1000'
const cardRequest: CardRequest = {
    programName: 'SKRILL-VIRTUAL-MC-EEA',
    currency: 'BGN',
    mobile: '+1 123456789',
    cardPin: null,
    externalId: null,
    deliveryAddress: null,
    termsAndConditionsAccepted: true,
    eDisclosureAccepted: true

    .then(response => console.log('Created card', response))
    .catch(error => console.error('Error creating card', error));

The parameters for PHYSICAL card application are the same, but you need to specify the deliveryAddress parameter.

const cardRequest: CardRequest = {
    programName: 'SKRILL-PHYSICAL-MC-EEA',
    currency: 'BGN',
    mobile: '+1 123456789',
    cardPin: null,
    externalId: null,
    deliveryAddress: {
        address1: 'Tsarigradsko Shose 73',
        address2: null,
        address3: null,
        city: 'Sofia',
        countryCode: 'BG',
        state: null,
        postalCode: '1000'
    termsAndConditionsAccepted: true,
    eDisclosureAccepted: true

    .then(response => console.log('Created card', response))
    .catch(error => console.error('Error creating card', error));

Update prepaid card status

The customer can change/update the status of their prepaid cards, and as a result, lock/unlock or cancel their prepaid card.


Parameter Type Description Example
status CardStatus Optional parameter containing information about the different card statuses. CardStatus.ACTIVE
statusReason string Optional parameter for specifying the reason for card status change. 'User Activate Card from LOCKED status'
pin string Optional parameter. The card pin should be 4 digits. '1243'
const cardUpdateRequest: CardUpdateRequest = {
    status: CardStatus.ACTIVE,
    statusReason: 'User Activate Card from LOCKED status',
    pin: '1243'
const cardId = 'f16ba382-eb42-481a-b08f-c57bdc9aae24';

Wallet.getInstance().getCardService().update(cardId, cardUpdateRequest)
    .then(response => console.log('Updated card', response))
    .catch(error => console.error('Error updating card', error));

Get prepaid card details

Card sensitive information can be retrieved. The response contains card sensitive information such as pan, cvv, expiry, cardHolderName.

    .then(response => console.log('Card details', response))
    .catch(error => console.error('Error getting card details', error));

Get prepaid card details url

Sensitive card information can be retrieved using a special url which can be retrieved by the following method. Language parameter is optional and default to en-US. The response contains the url which will load sensitive card details.

Wallet.getInstance().getCardService().getDetailsUrl('f16ba382-eb42-481a-b08f-c57bdc9aae24', 'en-GB')
    .then(response => console.log('Card details url', response))
    .catch(error => console.error('Error getting card details url', error));

Retrieve customer eligible prepaid cards programs

Retrieve eligible programs for a customer. The result list can be filtered by program type. If the customer is eligible for a Prepaid card, the response will contain a non-empty programs array. The number of cards that can be issued of a given type can be seen in the allowableCards field.

    .then(response => console.log('Programs list', response))
    .catch(error => console.error('Error fetching programs', error));
On this Page