Cards

Create Card

Endpoint

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

Description

This API creates a card — virtual or physical — for a cardholder, based on the card_type specified in the request payload. It also allows configuration of card-level details such as:

Spend controls — e.g., transaction limits, allowed transaction count.
Usage type — single-use or multi-use.

For more details, refer to the Cards Guide.

Note:

For the Cards program, this API supports only virtual card creation. To issue a physical card, use the separate Assign Card API instead.

For Cards under Banking, this API supports both virtual and physical card creation directly.

Virtual cards are activated automatically upon creation, while physical cards require activation via the Activate Card API after they are received.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

card_issuance_action string required

Card issuance type. Allowed values: NEW, REPLACEMENT

card_type string required

Type of card. Allowed values: PHYSICAL, VIRTUAL

card_holder_id string required

The ID of the cardholder to associate this card with.

created_by string required

Full legal name of user requesting new card

request_id string required

Unique request ID used for idempotency

program object required

Program details for card issuance.

purpose string required

Purpose of the card. Allowed value: COMMERCIAL.

authorization_controls object required

Transaction control configurations.

allowed_transaction_count string required

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

transaction_limits object required

Configuration for transaction limits.

currency string required

Currency for transaction limits (3-letter ISO-4217 code)

limits array required

Transaction limits are based on interval and amount

amount double required

Transaction limit amount. Must be greater than 0.

interval string required

Limit interval: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

postal_address object conditional

Delivery detail of the card. Only available for physical cards

city string required

City name.

country string required

Country code (2-letter ISO 3166-2 code).

line1 string required

Street address line 1.

state string required

State or province.

postcode string required

Postal or ZIP code.

is_personalized boolean required

Indicates whether the card is assigned to a single individual or to the business with multiple authorized users. Only personalized cards can be physical and added to digital wallets.

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "card_issuance_action": "NEW",
  "card_type": "PHYSICAL",
  "card_holder_id": "{{CardholderID}}",
  "created_by": "Postman Test",
  "request_id": "{{IdempotencyKey}}",
  "program": {
    "purpose": "COMMERCIAL"
  },
  "authorization_controls": {
    "allowed_transaction_count": "MULTIPLE",
    "transaction_limits": {
      "currency": "SGD",
      "limits": [
        {
          "amount": 10000,
          "interval": "PER_TRANSACTION"
        }
      ]
    }
  },
  "postal_address": {
    "city": "Singapore",
    "country": "SG",
    "line1": "21 Pasir Ris Street 72",
    "state": "Singapore",
    "postcode": "518764"
  },
  "is_personalized": true
}'

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card"

payload = json.dumps({
  "card_issuance_action": "NEW",
  "card_type": "PHYSICAL",
  "card_holder_id": "{{CardholderID}}",
  "created_by": "Postman Test",
  "request_id": "{{IdempotencyKey}}",
  "program": {
    "purpose": "COMMERCIAL"
  },
  "authorization_controls": {
    "allowed_transaction_count": "MULTIPLE",
    "transaction_limits": {
      "currency": "SGD",
      "limits": [
        {
          "amount": 10000,
          "interval": "PER_TRANSACTION"
        }
      ]
    }
  },
  "postal_address": {
    "city": "Singapore",
    "country": "SG",
    "line1": "21 Pasir Ris Street 72",
    "state": "Singapore",
    "postcode": "518764"
  },
  "is_personalized": True
})
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'Content-Type': 'application/json',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-user-id': '{{UserID}}',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n      \"card_issuance_action\": \"NEW\",\r\n      \"card_type\": \"PHYSICAL\",\r\n      \"card_holder_id\": \"{{CardholderID}}\",\r\n      \"created_by\": \"Postman Test\",\r\n      \"request_id\": \"{{IdempotencyKey}}\", \n      \"program\": {\r\n        \"purpose\": \"COMMERCIAL\"},\r\n      \"authorization_controls\": {\r\n        \"allowed_transaction_count\": \"MULTIPLE\",\r\n        \"transaction_limits\": {\r\n          \"currency\": \"SGD\",\r\n          \"limits\": [\r\n            {\r\n              \"amount\": 10000,\r\n              \"interval\": \"PER_TRANSACTION\"\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"postal_address\": {\r\n            \"city\": \"Singapore\",\r\n                \"country\": \"SG\",\r\n                \"line1\": \"21 Pasir Ris Street 72\",\r\n                \"state\": \"Singapore\",\r\n                \"postcode\": \"518764\"\r\n      },\r\n      \"is_personalized\": true\r\n    }");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "card_issuance_action": "NEW",
  "card_type": "PHYSICAL",
  "card_holder_id": "{{CardholderID}}",
  "created_by": "Postman Test",
  "request_id": "{{IdempotencyKey}}",
  "program": {
    "purpose": "COMMERCIAL",
    "type": "DEBIT"
  },
  "authorization_controls": {
    "allowed_transaction_count": "MULTIPLE",
    "transaction_limits": {
      "currency": "SGD",
      "limits": [
        {
          "amount": 10000,
          "interval": "PER_TRANSACTION"
        }
      ]
    }
  },
  "postal_address": {
    "city": "Singapore",
    "country": "SG",
    "line1": "21 Pasir Ris Street 72",
    "state": "Singapore",
    "postcode": "518764"
  },
  "is_personalized": true
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Card created successfully.",
  "data": {
    "id": "card-id"
  }
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Assign Card

This API assigns a physical card to a cardholder.

Endpoint

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

Description

This API is used to assign 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.

Note: This API is applicable only to the Cards program. For Cards under Banking, physical cards can be created directly via the Create Card API.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

cardholder_id string required

Unique identifier for the cardholder.

card_number string required

The physical card number to be assigned to the cardholder.

card_currency string required

The currency of the card being assigned (3-letter ISO-4217 code).

card_mode string required

Allowed value: SINGLE.
SINGLE indicates a prepaid card, which must be loaded with funds before it can be used.

createdBy string required

Identifier or name of the user creating this request.

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card/assign' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "cardholder_id": "cardholder-id",
  "card_number": "card-number",
  "card_currency": "USD",
  "card_mode": "SINGLE",
  "created_by": "admin_user"
}'   

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card/assign"

payload = json.dumps({
  "cardholder_id": "cardholder-id",
  "card_number": "card-number",
  "card_currency": "USD",
  "card_mode": "SINGLE",
  "created_by": "admin_user"
})
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"cardholder_id\": \"cardholder-id\",\r\n  \"card_number\": \"card-number\",\r\n  \"card_currency\": \"USD\",\r\n  \"card_mode\": \"SINGLE\",\r\n  \"created_by\": \"admin_user\"\r\n}");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/assign")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "cardholder_id": "cardholder-id",
  "card_number": "card-number",
  "card_currency": "USD",
  "card_mode": "SINGLE",
  "created_by": "admin_user"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/assign',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Card assign successfully."
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Get All Cards

Endpoint

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

Description

This endpoint returns a list of all cards (both physical and virtual) associated with the authenticated user. The response includes key card attributes such as card status, masked number, type, associated cardholder ID, and timestamps for creation and updates.
You can also filter the results using query parameters such as card ID, cardholder ID and card status to retrieve specific card records.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

cardholder_id string

Unique identifier for cardholder

id string

Unique identifier for card

status string

Card status filter. Allowed values: ACTIVE, INACTIVE

page_num integer

Page number for pagination

page_size integer

Number of items per page

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests

url = "{{baseUrl}}/zoqq/api/v1/card"

headers = {
  "x-api-key": "{{Shared X-API key By Zoqq}}",
  "x-product-id": "{{Shared ProductID By Zoqq}}",
  "x-request-id": "{{IdempotencyKey}}",
  "x-user-id": "{{UserID}}",
  "Content-Type": "application/json", 
  "Authorization": "Bearer {{AccessToken}}"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{baseUrl}}/zoqq/api/v1/card"))
  .header("x-api-key", "{{Shared X-API key By Zoqq}}")
  .header("x-product-id", "{{Shared ProductID By Zoqq}}")
  .header("x-request-id", "{{IdempotencyKey}}")
  .header("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .header("Authorization", "Bearer {{AccessToken}}")
  .method("GET", HttpRequest.BodyPublishers.noBody())
  .build();
HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Card fetched successfully",
  "data": [
    {
      "cardHashId": "card-hash-id",
      "cardStatus": "ACTIVE",
      "maskedCardNumber": "************4639",
      "cardholderId": "",
      "createdAt": "2025-04-02T07:36:56.973+0000",
      "updatedAt": "2025-04-23T05:45:12.422+0000",
      "nameOnCard": "Postman Test",
      "cardType": "VIRTUAL",
      "currency": "USD"
    },
    {
      "cardHashId": "card-hash-id",
      "cardStatus": "INACTIVE",
      "maskedCardNumber": "************6886",
      "cardholderId": "",
      "createdAt": "2025-03-31T08:02:20.000+0000",
      "updatedAt": "2025-03-31T08:02:20.000+0000",
      "nameOnCard": "demozoqq",
      "cardType": "PHY",
      "currency": "SGD"
    }
  ]
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Show Card Details

Endpoint

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

Description

This endpoint returns sensitive card details that are typically masked in other endpoints.

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

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

id string required

Unique identifier for card

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card/detail?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests

url = "{{baseUrl}}/zoqq/api/v1/card/detail"
params = {
  "id": "{{CardID}}"
}

headers = {
  "x-api-key": "{{Shared X-API key By Zoqq}}",
  "x-product-id": "{{Shared ProductID By Zoqq}}",
  "x-request-id": "{{IdempotencyKey}}",
  "x-user-id": "{{UserID}}",
  "Content-Type": "application/json",
  "Authorization": "Bearer {{AccessToken}}"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{baseUrl}}/zoqq/api/v1/card/detail?id={{CardID}}"))
  .header("x-api-key", "{{Shared X-API key By Zoqq}}")
  .header("x-product-id", "{{Shared ProductID By Zoqq}}")
  .header("x-request-id", "{{IdempotencyKey}}")
  .header("x-user-id", "{{UserID}}")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer {{AccessToken}}")
  .method("GET", HttpRequest.BodyPublishers.noBody())
  .build();
HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/detail?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "status": "success",
  "message": "Card details fetched successfully.",
  "code": 200,
  "data": [
    {
      "personalized": true,
      "card_id": "card-id",
      "card_bin": null,
      "card_scheme": "VISA",
      "card_currency": "SGD",
      "card_number": "************2145",
      "form_factor": "PHYSICAL",
      "mode_type": null,
      "card_product_id": null,
      "card_limit": 15000.0,
      "available_balance": null,
      "cardholder": {
        "cardholder_id": "cardholder-id",
        "email": "",
        "number_of_cards": null,
        "first_name": "",
        "last_name": null,
        "create_time": "2025-08-27T12:04:10.912+0000",
        "cardholder_status": null,
        "date_of_birth": null,
        "country_code": "SG",
        "phone_number": ""
      },
      "spending_controls": [
        {
          "amount": 15000.0,
          "interval": "PER_TRANSACTION",
          "remaining": 15000.0
        }
      ],
      "authorization_controls": {
        "active_from": "2025-08-27T00:00:00.000+00:00",
        "active_to": "2025-12-31T23:59:59.000+00:00",
        "allowed_currencies": [
          "USD",
          "EUR",
          "INR"
        ],
        "allowed_merchant_categories": []
      },
      "no_pin_payment_amount": null,
      "risk_controls": null,
      "metadata": {},
      "card_status": "INACTIVE",
      "brand": "VISA",
      "cardholder_id": "cardholder-id",
      "created_at": null,
      "created_by": "user",
      "is_personalized": true,
      "name_on_card": "John Doe",
      "nick_name": "Testair",
      "program": {
        "purpose": "COMMERCIAL",
        "type": "DEBIT"
      },
      "purpose": null,
      "delivery_details": {
        "delivery_mode": "MAIL",
        "delivery_vendor": "DHL",
        "status": "PRINTED",
        "tracked": true,
        "tracking_link": "tracking-link",
        "tracking_number": "ABCD1234",
        "updated_at": "2026-02-06T00:00:00.000+0000"
      },
      "postal_address": {
        "city": "Singapore",
        "country": "SG",
        "line1": "21 Pasir Ris Street 72",
        "line2": "null",
        "postcode": "518764",
        "state": "Singapore"
      }
    }
  ]
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Activate Card

Endpoint

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

Description

This API is used to activate a physical card for card payment authorizations.

For cards assigned via the Assign Physical 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.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

activation_code string conditional

Activation code received via email when the physical card was assigned.

pin string conditional

6-digit PIN to be set for the card.

🔍 Query Parameters

id string required

Unique identifier for card to activate

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card/activate?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card/activate?id={{CardID}}"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'Content-Type': 'application/json',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-user-id': '{{UserID}}',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/activate?id={{CardID}}")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/activate?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "card activated successfully"
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Reset PIN

This API resets the PIN for a assigned physical card.

Endpoint

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

Description

This API is program specific and used to reset the PIN for a card assigned via the Assign Physical Card API.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

pin string required

6-digit PIN to be set for the card.

🔍 Query Parameters

id string required

Unique identifier for card to reset PIN

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card/pin?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "pin": "123456"
}'    

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card/pin?id={{CardID}}"

payload = json.dumps({
  "pin": "123456"
})
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n        \"pin\": \"123456\"\n    }");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/pin?id={{CardID}}")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "pin": "123456"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/pin?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Pin reset successfully."
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Update Card

This API updates card details including authorization controls and status.

Endpoint

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

Description

This endpoint updates card details by setting the values of the included parameters. Parameters that are not included will be left unchanged.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

card_status string

Card status. Allowed values: ACTIVE, INACTIVE, CLOSED.

currency string

Currency for transaction limits (3-letter ISO-4217 code).

transaction_limits array

Array of transaction limits.

type string required

Type of limit. Allowed values: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

value double required

Numerical value of the transaction limit.

authorization_controls object

Controls for restricting card authorization.

active_from string

Start date-time from which card is active (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ).

active_to string

End date-time until which card remains active. (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ).

allowed_currencies array of string

Allowed currencies for card transactions following 3-letter ISO-4217 currency code.
(e.g.: ["USD", "EUR"]).

allowed_merchant_categories array of string

Allowed merchant category codes (4-digit MCCs).

updated_by string required

User updating the details

🔍 Query Parameters

id string required

Unique identifier for card to update

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request PATCH \
--url '{{baseUrl}}/zoqq/api/v1/card?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "card_status": "ACTIVE",
  "currency": "USD",        
  "transaction_limits": [
    {
      "type": "DAILY",
      "value": 1
    }
  ],
  "authorization_controls": {
    "active_from": "2025-05-01T00:00:00Z",
    "active_to": "2025-12-31T23:59:59Z",
    "allowed_currencies": ["USD", "EUR", "INR"],
    "allowed_merchant_categories": ["5411", "5732", "5999"]
  },
  "updated_by": "test"
}'

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card?id={{CardID}}"

payload = json.dumps({
  "card_status": "ACTIVE",
  "currency": "USD",
  "transaction_limits": [
    {
      "type": "DAILY",
      "value": 1
    }
  ],
  "authorization_controls": {
    "active_from": "2025-05-01T00:00:00Z",
    "active_to": "2025-12-31T23:59:59Z",
    "allowed_currencies": [
      "USD",
      "EUR",
      "INR"
    ],
    "allowed_merchant_categories": [
      "5411",
      "5732",
      "5999"
    ]
  },
  "updated_by": "test"
})
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'Content-Type': 'application/json',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-user-id': '{{UserID}}',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"card_status\": \"ACTIVE\",\n    \"currency\": \"USD\",        \n    \"transaction_limits\": [\n        {\n            \"type\": \"DAILY\",\n            \"value\": 1\n        }\n    ],\n    \"authorization_controls\": {\n    \"active_from\": \"2025-05-01T00:00:00Z\",\n    \"active_to\": \"2025-12-31T23:59:59Z\",\n    \"allowed_currencies\": [\"USD\", \"EUR\", \"INR\"],\n    \"allowed_merchant_categories\": [\"5411\", \"5732\", \"5999\"],\n \"updated_by\": \"test\"\n} ");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card?id={{CardID}}")
  .method("PATCH", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "card_status": "ACTIVE",
  "currency": "USD",
  "transaction_limits": [
    {
      "type": "DAILY",
      "value": 1
    }
  ],
  "authorization_controls": {
    "active_from": "2025-05-01T00:00:00Z",
    "active_to": "2025-12-31T23:59:59Z",
    "allowed_currencies": [
      "USD",
      "EUR",
      "INR"
    ],
    "allowed_merchant_categories": [
      "5411",
      "5732",
      "5999"
    ]
  },
  "updated_by": "test"
});

let config = {
  method: 'patch',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "card updated successfully"
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Load Card

Recharge / Load Funds to Card

Endpoint

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

Description

Adds funds to a specific card associated with the authenticated user. This API performs a card recharge (load) operation and credits the specified amount to the card balance. The card to be recharged is identified using the id query parameter.

Note: This API is supported only for specific programs where card recharge/load functionality has been enabled and configured. Please contact Zoqq to confirm whether this feature is available for your program.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body Parameters

amount double required

Amount to be funded to the card. Must be greater than 0.

🔍 Query Parameters

id string required

Unique identifier for card

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card/recharge?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data '{
  "amount": 100.0
}'

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card/recharge?id={{CardID}}"

payload = json.dumps({
  "amount": 100.0
})
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"amount\": 100.0\r\n}");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/recharge?id={{CardID}}")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "amount": 100.0
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/recharge?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Card recharge successfully." 
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Get Card Transactions

Endpoint

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

Description

This endpoint returns a paginated list of transactions for a specific card, including detailed merchant information, transaction amounts, and status.

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

x-product-id string required

Shared Product ID by Zoqq

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

id string required

Unique identifier for card

page_num integer

Page number for pagination

page_size integer

Number of items per page

from_created_at string conditional

Start date to filter records created on or after this date. (ISO 8601 date format: YYYY-MM-DD). Must be provided together with to_created_at.

to_created_at string conditional

End date to filter records created on or before this date. (ISO 8601 date format: YYYY-MM-DD). Must be provided together with from_created_at.

🧩 Examples
🧪 Try It Out

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key By Zoqq}}',
  'x-request-id': '{{IdempotencyKey}}',
  'Content-Type': 'application/json',
  'x-product-id': '{{Shared ProductID By Zoqq}}',
  'x-user-id': '{{UserID}}',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}")
  .method("GET", body)
  .addHeader("x-api-key", "{{Shared X-API key By Zoqq}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-product-id", "{{Shared ProductID By Zoqq}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}',
  headers: { 
    'x-api-key': '{{Shared X-API key By Zoqq}}', 
    'x-product-id': '{{Shared ProductID By Zoqq}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

200: Success
400: Error

{
  "code": 200,
  "status": "success",
  "message": "Card transaction fetched successfully.",
  "data": {
    "has_more": true,
    "items": [
      {
        "acquiring_institution_identifier": "123456",
        "auth_code": "000001",
        "billing_amount": 100,
        "billing_currency": "USD",
        "card_id": "",
        "card_nickname": "string",
        "client_data": "Some client data",
        "digital_wallet_token_id": "",
        "failure_reason": "INSUFFICIENT_FUNDS",
        "lifecycle_id": "",
        "masked_card_number": "************4242",
        "matched_authorizations": [
          "6c2dc266-09ad-4235-b61a-767c7cd6d6ea"
        ],
        "merchant": {
          "category_code": "4829",
          "city": "San Francisco",
          "country": "USA",
          "identifier": "012345678910123",
          "name": "Merchant A",
          "postcode": "94111",
          "state": "CA"
        },
        "network_transaction_id": "3951729271768745",
        "posted_date": "2018-03-22T16:08:02+00:00",
        "retrieval_ref": "909916088001",
        "risk_details": {
          "risk_actions_performed": [
            "TRANSACTION_BLOCKED"
          ],
          "risk_factors": [
            "Suspicious transaction velocity"
          ],
          "three_dsecure_outcome": "AUTHENTICATED"
        },
        "status": "APPROVED",
        "transaction_amount": 100,
        "transaction_currency": "USD",
        "transaction_date": "2018-03-21T16:08:02+00:00",
        "transaction_id": "transactionid",
        "transaction_type": "REFUND"
      }
    ]
  }
}

{
  "code": 400,
  "status": "Error",
  "message": "Error Message"
}

Create Card​

Description

📩 Request Headers

📦 Request Body Parameters

Request Example

Response Example

💳 Create Card — Sandbox

🔐 Headers

📝 Request Body

💻 Generated cURL Command

Assign Card​

Description

📩 Request Headers

📦 Request Body Parameters

Request Example

Response Example

Get All Cards​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

📂 Get All Cards — Sandbox

🔐 Headers

🔍 Query Parameters (Optional)

💻 Generated cURL Command

Show Card Details​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

💳 Get Card Details — Sandbox

🔐 Headers

🔍 Query Parameter

💻 Generated cURL Command

Activate Card​

Description

📩 Request Headers

📦 Request Body Parameters

🔍 Query Parameters

Request Example

Response Example

💳 Activate Card — Sandbox

🔐 Headers

🔍 Query Parameters

📝 Request Body (Conditional)

💻 Generated cURL Command

Reset PIN​

Description

📩 Request Headers

📦 Request Body Parameters

🔍 Query Parameters

Request Example

Response Example

Update Card​

Description

📩 Request Headers

📦 Request Body Parameters

🔍 Query Parameters

Request Example

Response Example

🛠 Update Card — Sandbox

🔐 Headers

🔍 Query Parameters

📝 Request Body

💻 Generated cURL Command

Load Card​

Description

📩 Request Headers

📦 Request Body Parameters

🔍 Query Parameters

Request Example

Response Example

Get Card Transactions​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

Create Card

Assign Card

Get All Cards

Show Card Details

Activate Card

Reset PIN

Update Card

Load Card

Get Card Transactions