Overview

The Card Management system in Qolo enables clients to efficiently issue, fund, and control cards while ensuring security and compliance. This guide provides details on card issuance methods, funding mechanisms, transactions, and other controls.

Card Types

Qolo supports different types of cards based on usage models.

Virtual vs. Physical Cards

• Virtual Cards: Issued instantly for online transactions.
• Physical Cards: Issued as plastic cards with chip and/or magnetic stripe for in-store and online transactions.

Card Issuance

Cards can be issued using different methods, depending on how they are distributed and assigned to cardholders.

Individual vs. Bulk Card Issuance

Individual Card Issuance

• Cards are issued directly to the cardholder.
• Physical cards are shipped to the address on file.
• Virtual cards are available immediately upon creation.

For information about how to create a card, refer to the Recipe below:

Bulk Card Issuance

Clients can request bulk issuance, where multiple cards are produced and sent to a designated inventory location for further distribution.

Setting up an Inventory Location

An inventory location / inventory manager is identified as the address used for delivering bulk card orders.

In order to create an inventory manager, you must call the Create Person API and must send the person_details.contact_type as "INVENTORYMANAGER". The address for the Inventory Location must be sent in the person_details.base_address field.

POST /api/v1/persons/ HTTP/1.1
{
	person_details": {
		"first_name": "string",
    "middle_name": "string",
    "last_name": "string",
		"email": "string",  // Optional
		"contact_type": "INVENTORYMANAGER",  // Send INVENTORYMANAGER to set up an Inventory Location
		"base_address": {
			"city": "string",
      "country": "str",
      "address_line1": "string",
      "address_line2": "string",
      "postal_code": "string",
      "state": "string"
		},
	}
}

Bulk Issuance Types

• Bulk Anonymous:
  • Cards are shipped in bulk without being assigned to specific individuals.
  • Cards are later assigned to individuals at the inventory location.
  • Refer to the recipe below for bulk anonymous card order and process.

• Bulk Personalized:
  • Cards are pre-personalized with the cardholder’s details but sent in bulk to an inventory location.
  • The inventory manager then distributes the cards to the respective cardholders.
  • Refer to the recipe below for bulk anonymous card order and process.

Example Use Case:
A corporate payroll program might order bulk anonymous cards and distribute them to employees at different branch locations.

Activating a Card

Physical cards must be activated before use. This can be done via:

• Card Activation API
• Client portal
• IVR (Interactive Voice Response) service

For virtual cards, activation is typically instant upon creation.

Card Funding

Understanding Card Balances

Funds are not directly stored on the card. Instead, the card is associated to account in the same wallet. The account holds the balance and the transaction history.

• When a transaction is made, the system checks the balance in the associated account.
• If the account has sufficient funds, the transaction is approved.
• If the account lacks funds, the transaction is declined.

Example:

• A gig worker receives payments in their individual account. Their card transactions pull funds from this account.
• If their balance is low, they cannot complete a transaction until funds are added to the account.

Funding Models

There are two funding models that determine how funds are made available for card transactions:

Standard Funding

• The individual account must be funded before the card can be used.
• If the account lacks funds, the transaction declines.
• Funding sources can include:
  • Deposits from the program funding account.
  • Direct deposits (e.g., payroll)
  • Transfers from external accounts

Sparq Interact Funding

• Funds are transferred to the individual account at the time of transaction authorization, based on the transaction amount.
• The client may participates in the authorization process to approve or deny transactions dynamically.
• This allows real-time funding, ensuring that transactions succeed without requiring a preloaded balance.
  Example Use Case:
• A corporate expense program may enable Interact funding, so employee transactions are only funded if they meet company spending policies.

Card Status Management

Card statuses help manage card usage, security, and lifecycle events. There are two types of card status that serve different purposes:

• card_status – Managed by the client or program manager to control the overall state of the card.
• person_card_status – Managed by the cardholder to temporarily lock or unlock their card without affecting the underlying card status.

Card Status

The card_status reflects the overall status of the card and is primarily controlled by the client or program manager. It determines whether the card is active, suspended, or permanently closed.

Possible Values

Example Use Case:

If a cardholder reports suspicious activity, the program manager can suspend the card by updating card_status to SUSPENDED.

Person Card Status

The person_card_status allows a cardholder to lock or unlock their card without affecting the underlying card_status. This provides a way for users to temporarily restrict card usage without requiring administrative intervention.

This is usually facilitated by a cardholder app or IVR that calls the appropriate Qolo API on customer request to lock/unlock the card.

Possible Values

Example Use Case:

A cardholder misplaces their card and locks it using person_card_status. Once they find it, they unlock it without requiring action from the program manager.

API References

Key API Endpoints

• Create Card: Issues a new card under a program, either for an individual or as part of bulk issuance.
  POST /api/{version}/cards
• Assign Card: Links a bulk-issued anonymous card to a specific cardholder, making it ready for activation.
  POST /api/{version}/cards/assign
• Activate Card: Enables a newly issued or assigned card for transactions.
  POST /api/{version}/cards/{card_proxy}/activate
• Update Card Status: Modifies the status of a card (e.g., activate, suspend, close) as per program or cardholder actions.
  POST /api/{version}/cards/{card_proxy}/status
• Replace Card: Issues a replacement card for a lost, stolen, or damaged card while maintaining the account association.
  POST /api/{version}/cards/{card_proxy}/replace
• Validate Card: Verifies if a card and cardholder details are valid for confirming cardholder possession of the card; as part of the authentication process of a cardholder website, app or IVR.
  POST /api/{version}/cards/validate
• Set PIN: Allows a cardholder to set or reset their card’s PIN for secure transactions.
  POST /api/{version}/cards/{card_proxy}/pin
• Get PIN: Retrieves PIN-related details based on card network requirements (e.g., PIN offset retrieval).
  GET /api/{version}/cards/{card_proxy}/pin