Cards Integration Guide

Zoqq Cards APIs allow you to create cardholders, issue cards, control usage, and track transactions programmatically. This guide walks you through the recommended integration flow.

Zoqq Issuing Overview

Zoqq Issuing enables businesses to issue and manage multi-currency Visa cards at scale while controlling spending and monitoring transactions programmatically.

Zoqq-issued cards are connected directly to your Zoqq Wallet, allowing funds to be used without locking balances onto individual cards.

Key Features

Zoqq Issuing provides a flexible card infrastructure designed for global businesses.

Key capabilities include:

Provisioning of Visa cards through Zoqq’s global issuing infrastructure
Issue single-use or multi-use cards
Support for business cards and individual cards
Real-time authorization controls
RESTful APIs to manage your entire card program
Flexible funding structures using your Zoqq Wallet
Whitelabeling capabilities to customize card programs

Zoqq cards are funded directly from your Zoqq Wallet, allowing centralized treasury management across all issued cards.

What You Can Do with Cards

Using Zoqq Cards APIs, you can:

Create and manage cardholders
Retrieve cardholder details and list all cardholders
Issue cards to cardholders
View cards by cardholder or retrieve individual card details
Activate cards after issuance
Update card settings when required
Track card transactions for issued cards
Load funds onto issued cards (program-dependent)
Programmatically manage the full card lifecycle using secure APIs

All card operations are performed securely using authenticated, idempotent APIs.

Operations

# Cardholder Endpoints
> POST   {{baseUrl}}/zoqq/api/v1/card/cardholder
> GET    {{baseUrl}}/zoqq/api/v1/card/cardholder
> PATCH  {{baseUrl}}/zoqq/api/v1/card/cardholder
> DELETE {{baseUrl}}/zoqq/api/v1/card/cardholder

# Card Endpoints
> POST   {{baseUrl}}/zoqq/api/v1/card
> POST   {{baseUrl}}/zoqq/api/v1/card/assign
> GET    {{baseUrl}}/zoqq/api/v1/card
> GET    {{baseUrl}}/zoqq/api/v1/card/detail
> POST   {{baseUrl}}/zoqq/api/v1/card/activate
> POST   {{baseUrl}}/zoqq/api/v1/card/pin
> PATCH  {{baseUrl}}/zoqq/api/v1/card
> GET    {{baseUrl}}/zoqq/api/v1/card/transaction
> POST   {{baseUrl}}/zoqq/api/v1/card/recharge

Issuing Capabilities

Zoqq provides infrastructure to issue and manage cards globally.

Issue Cards

Issue cards for employees, partners, or platform users.

Set Spending Controls

Configure card spending rules such as:

Transaction limits
Merchant category restrictions
Currency restrictions
Authorization rules

Manage Cards

Cards can be managed through APIs.

Supported actions include:

Freeze or unfreeze cards
Cancel cards
Update authorization controls
Retrieve card details

Supported Regions and Currencies

Zoqq-issued cards are multi-currency Visa cards that support transactions in 140+ currencies worldwide.

Transactions are funded directly from your Zoqq Wallet balance.

Direct Billing

Direct Billing allows Zoqq to debit the same currency from your wallet balance when available.

Supported currencies include:

USD
AUD
CAD
SGD
NZD
HKD
JPY
EUR
GBP
CHF
ILS¹

¹ Available only for cards issued to businesses based in Israel.

If a transaction occurs in a currency not listed above, Zoqq will debit the equivalent amount from your base currency wallet using Visa’s daily exchange rate.

Other Currency Transactions

For currencies not listed in Direct Billing, Zoqq will debit an equivalent amount from your base currency Wallet.

The conversion rate follows Visa’s daily FX exchange rate.

Example:

If a transaction occurs in AED, your base currency Wallet will be debited for an equivalent amount based on Visa’s exchange rate.

Supported Card Programs

Zoqq supports multiple card program configurations depending on business requirements.

These programs determine the Bank Identification Number (BIN) and program structure used when issuing cards.

Program Structure

Brand: Currently supported brand: Visa

Program Purpose

Cards can be issued as:

Commercial cards – used for business expenses
Consumer cards – used for end-user payouts or spending

Note: For the Cards program, only commercial cards are supported. For Cards under Banking, both commercial and consumer cards are supported.

Cardholder Types

Supported cardholder types include:

Delegate – representative acting on behalf of the business
Individual – card issued to a named user

Personalization Options

Cards can be issued as:

Personalized cards – issued to a specific individual
Non-personalized cards – associated with the business

Card Forms

Cards can be issued as:

Virtual cards
Physical cards

Program Type

Zoqq currently supports the following card program type:

Debit – Transactions are funded directly from the Zoqq Wallet balance at the time of purchase.

When a transaction is authorized, the required amount is deducted from the associated Zoqq Wallet balance.

Program Sub-Types

Examples include:

Good Funds Credit – requires available funds before authorization
B2B Travel Programs

Commercial Cards

Feature	Commercial
Suited For	Business expenses, supplier payments, operational spending
Personalization	Supported
Cardholder Types	Delegate or Individual
Card Form	Virtual or Physical
Name on Card	Business name (non-personalized) or individual name (personalized)
Fund Ownership	Business wallet
Access to Sensitive Details	Direct API (non-personalized) or secure iframe
PIN	Not supported for non-personalized cards
Card Management	Edit, freeze, cancel
Card Controls	Supported
Whitelabeling	Supported

Personalized vs Non-Personalized Cards

Feature	Non-personalized	Personalized
Name on Card	Business name	Individual legal name
Card Association	Multiple users may access the card	Assigned to a single individual
Sensitive Data Access	Direct API	Secure iframe
Supported Features	Virtual cards	Virtual or Physical cards

Card Form Comparison

Feature	Virtual	Physical
Description	Digital card details used for online transactions	Physical card issued to cardholder
Non-personalized	Supported	Not supported
Personalized	Supported	Supported
Activation	Automatically activated	Manual activation or API activation required

Integration Flow (Recommended)

Step 1: Create a Cardholder

Before issuing any card, you must create a cardholder.

Cardholders represent authorized users of your business and can be of two types:

INDIVIDUAL
- Associated with a named person
- Can be issued personalized or non-personalized cards
DELEGATE
- Used only for non-personalized cards
- Cards are issued in the business name

Creating a cardholder triggers a name screening process.

Note: For the Cards program, only the INDIVIDUAL cardholder type is supported. For Cards under Banking, both INDIVIDUAL and DELEGATE cards are supported.

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card/cardholder

Step 2: Retrieve or Manage Cardholders

You can list, view, update, or delete cardholders at any time.

Supported actions:

Get all cardholders (with pagination and status filtering)
Get cardholder details by ID
Update cardholder contact or address details
Delete a cardholder (irreversible)

Endpoints

GET    {{baseUrl}}/zoqq/api/v1/card/cardholder
PATCH  {{baseUrl}}/zoqq/api/v1/card/cardholder
DELETE {{baseUrl}}/zoqq/api/v1/card/cardholder

Step 3: Create or Assign Card

Create a Card

Once a cardholder is ready, you can issue a card.

Cards can be:

VIRTUAL or PHYSICAL
Personalized or Non-personalized

During card creation, you can define:

Card type and issuance action
Program details
Spending and authorization controls
Delivery address (for physical cards)

Note:

For the Cards program, only virtual cards can be created directly. To issue a physical card, use the separate Assign Physical Card API.

For Cards under Banking, both virtual and physical cards can be created directly.

Virtual cards are activated automatically upon creation and are ready for use immediately. Physical cards require activation after they are received — see the Activate Card API.

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card

Assign Card

For programs where physical cards cannot be created directly via the Create Card API, use the Assign Card API instead.

This API assigns a pre-issued physical card to an existing cardholder. The physical card is identified using its card number and is then linked to the specified cardholder, making it available for use.

Once assigned, the card must be activated before it can be used for payments — see the Activate Card API.

Note: This flow applies to the Cards program, where card creation only supports virtual cards. For Cards under Banking, physical cards can be created directly via the Create Card API and this step is not required.

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card/assign

Step 4: Retrieve Cards

You can retrieve cards in multiple ways:

List all cards
Filter by card status or card ID
Fetch cards for a specific cardholder

Endpoint

GET {{baseUrl}}/zoqq/api/v1/card

Step 5: View Card Details

For use cases requiring deeper visibility (e.g. customer support or reconciliation), you can fetch detailed card information.

This endpoint returns sensitive card configuration and authorization controls.

Endpoint

GET {{baseUrl}}/zoqq/api/v1/card/detail

Note: For displaying sensitive card details to end users in a PCI-compliant manner, refer to the Secure Iframe Guide.

Step 6: Activate a Card

Physical cards must be activated before they can be used for transactions.

For cards assigned via the Assign Card API, the request body must include:

{
  "activation_code": "111222333",
  "pin": "123456"
}

activation_code: The activation code received via email at the time of assigning the physical card.
pin: The 6-digit PIN to be set for the card.

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card/activate

Reset PIN

This applies only to the Cards program.

For cards issued via the Assign Card API, the PIN is set during the Activate Card step.

The Reset PIN API is used to reset the PIN afterward, whenever the cardholder needs to set a new PIN for the card.

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card/pin

Step 7: Update Card Controls or Status

You can update:

Card status (ACTIVE, INACTIVE, CLOSED)
Authorization controls
Transaction limits
Allowed currencies and merchant categories

Updates are partial—only provided fields are modified.

Endpoint

PATCH {{baseUrl}}/zoqq/api/v1/card

Step 8: Fetch Card Transactions

Retrieve a paginated list of transactions for a card, including:

Merchant details
Transaction amount and currency
Status and risk indicators

Date range filters are supported.

Endpoint

GET {{baseUrl}}/zoqq/api/v1/card/transaction

Program Specific: Load Funds to a Card

Depending on the program configuration, funds may need to be loaded onto a card before it can be used for transactions.

For card programs that support or require card-level funding, use the Load Card API to transfer funds to the card.

For wallet-funded programs, transactions are funded directly from the associated Zoqq Wallet and this step is not required.

Typical use cases:

Initial card funding
Employee expense allocation
Contractor payouts
Periodic card top-ups

Endpoint

POST {{baseUrl}}/zoqq/api/v1/card/recharge

Key Notes for Developers

Cardholders must exist before issuing cards
Every card must be associated with an existing cardholder
Cardholder types (INDIVIDUAL / DELEGATE) supported depend on the program — some programs allow only INDIVIDUAL
Virtual cards are activated automatically upon creation
Physical cards require activation before use
For the Cards program, physical cards are issued via the Assign Physical Card API, and PIN is set during activation
For Cards under Banking, physical cards can be created directly via the Create Card API
Updates to cardholders or cards may re-trigger screening
All requests must include:
- Authentication headers
- Idempotency keys for safe retries
Pagination is supported on list and transaction APIs
Card funding requirements depend on the configured card program
Some programs use direct wallet funding and do not require card loading
For programs supporting card-level balances, use the Load Card API to fund cards

Typical Use Cases

Corporate expense cards
Employee or contractor cards
Controlled business spending
Transaction monitoring and reconciliation

Zoqq Issuing Overview​

Key Features​

What You Can Do with Cards​

Operations​

Issuing Capabilities​

Issue Cards​

Set Spending Controls​

Manage Cards​

Supported Regions and Currencies​

Direct Billing​

Other Currency Transactions​

Supported Card Programs​

Program Structure​

Program Purpose​

Cardholder Types​

Personalization Options​

Card Forms​

Program Type​

Program Sub-Types​

Commercial Cards​

Personalized vs Non-Personalized Cards​

Card Form Comparison​

Integration Flow (Recommended)​

Step 1: Create a Cardholder​

Step 2: Retrieve or Manage Cardholders​

Step 3: Create or Assign Card​

Create a Card​

Assign Card​

Step 4: Retrieve Cards​

Step 5: View Card Details​

Step 6: Activate a Card​

Reset PIN​

Step 7: Update Card Controls or Status​

Step 8: Fetch Card Transactions​

Program Specific: Load Funds to a Card​

Key Notes for Developers​

Typical Use Cases​

Zoqq Issuing Overview

Key Features

What You Can Do with Cards

Operations

Issuing Capabilities

Issue Cards

Set Spending Controls

Manage Cards

Supported Regions and Currencies

Direct Billing

Other Currency Transactions

Supported Card Programs

Program Structure

Program Purpose

Cardholder Types

Personalization Options

Card Forms

Program Type

Program Sub-Types

Commercial Cards

Personalized vs Non-Personalized Cards

Card Form Comparison

Integration Flow (Recommended)

Step 1: Create a Cardholder

Step 2: Retrieve or Manage Cardholders

Step 3: Create or Assign Card

Create a Card

Assign Card

Step 4: Retrieve Cards

Step 5: View Card Details

Step 6: Activate a Card

Reset PIN

Step 7: Update Card Controls or Status

Step 8: Fetch Card Transactions

Program Specific: Load Funds to a Card

Key Notes for Developers

Typical Use Cases