Skip to main content

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.

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

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