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
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
> GET    {{baseUrl}}/zoqq/api/v1/card
> GET    {{baseUrl}}/zoqq/api/v1/card/detail
> POST   {{baseUrl}}/zoqq/api/v1/card/activate
> PATCH  {{baseUrl}}/zoqq/api/v1/card
> GET    {{baseUrl}}/zoqq/api/v1/card/transaction

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

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 vs Consumer Cards

Feature	Commercial	Consumer
Suited For	Business expenses, supplier payments, operational spending	Payouts to individuals such as contractors or platform users
Personalization	Supported	Required
Cardholder Types	Delegate or Individual	Individual only
Card Form	Virtual or Physical	Virtual or Physical
Name on Card	Business name (non-personalized) or individual name (personalized)	Individual legal name
Fund Ownership	Business wallet	Customer wallet
Access to Sensitive Details	Direct API (non-personalized) or secure iframe	Secure iframe required
PIN	Not supported for non-personalized cards	Supported
Card Management	Edit, freeze, cancel	Edit, freeze, cancel
Card Controls	Supported	Supported
Whitelabeling	Supported	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.

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 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)

Endpoint

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

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

Step 6: Activate a Card

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

Endpoint

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

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

Key Notes for Developers

Cardholders must exist before issuing cards
Every card must be associated with an existing cardholder
Physical cards require activation before use
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

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 vs Consumer 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 a Card​

Step 4: Retrieve Cards​

Step 5: View Card Details​

Step 6: Activate a Card​

Step 7: Update Card Controls or Status​

Step 8: Fetch Card Transactions​

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 vs Consumer 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 a Card

Step 4: Retrieve Cards

Step 5: View Card Details

Step 6: Activate a Card

Step 7: Update Card Controls or Status

Step 8: Fetch Card Transactions

Key Notes for Developers

Typical Use Cases