Cards

You can create virtual cards associated with your organization. These cards can be single-use or multi-use and can be restricted by merchant category code, currency, and transactioYn amount.

Create Cardholder

Endpoint

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

Description

Cardholders are authorized representatives of your business. Two types of cardholders are permitted: Individual and Delegate.

INDIVIDUAL: A cardholder who is a named representative of your business. They can be issued either personalized or non-personalized cards.
DELEGATE: A cardholder assigned only to non-personalized cards. They act as authorized users on behalf of your business. Cards issued to delegate cardholders will be associated with the name of your business.

Creating a cardholder requires passing a name screening process, which involves submitting basic information about the cardholder.
This endpoint allows you to create a new cardholder by providing details such as personal information, address, and identification documents. The cardholder can be either an individual or a business entity.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description
type	string	Yes	Type of cardholder (must be "INDIVIDUAL" or "DELEGATE")
email	string	Yes	Cardholder's email address (must be valid format)
mobile_number	string	Yes	Cardholder's mobile number
individual	object	Yes	Required individual details
individual.name	object	Yes	First and last name
individual.name.first_name	string	Yes	First name
individual.name.last_name	string	Yes	Last name
individual.date_of_birth	string	Yes	Date of birth (format not specified)
individual.address	object	Yes	Physical address
individual.address.city	string	Yes	City
individual.address.country	string	Yes	Country
individual.address.line1	string	Yes	Address line 1
individual.address.state	string	Yes	State
individual.address.postcode	string	Yes	Postal code
individual.express_consent_obtained	string	No	Defaults to "YES"
postal_address	object	No	Mailing address (if different)
postal_address.city	string	Yes if present	City
postal_address.country	string	Yes if present	Country
postal_address.line1	string	Yes if present	Address line 1
postal_address.state	string	Yes if present	State
postal_address.postcode	string	Yes if present	Postal code
created_by	string	Yes	Creator identifier

Request Example

cURL

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v1/card/cardholder' \
--header 'x-api-key: {{Shared X-API key By Zoqq}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: application/json' \
--header 'x-product-id: {{Shared ProductID By Zoqq}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Authorization: Bearer {{AccessToken}}'
--data-raw '{
    "email": "testapiair78@yopmail.com",
    "individual": {
        "date_of_birth": "1990-01-01",
        "name": {
            "title": "miss",
            "first_name": "John",
            "middle_name":"P",
            "last_name": "Doe"
        },
        "address": {
            "city": "New York",
            "country": "SG",
            "line1": "123 5th Avenue",
            "state": "NY",
            "postcode": "10001"
        }
    },
    "mobile_number": "86689006",
    "postal_address": {
        "city": "New York",
        "country": "SG",
        "line1": "123 5th Avenue",
        "state": "NY",
        "postcode": "10001"
    },
    "type": "INDIVIDUAL",
    "created_by": "test"
}'

Python

import requests
import json

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

payload = json.dumps({
  "email": "test123@yopmail.com",
  "individual": {
    "date_of_birth": "1990-01-01",
    "name": {
      "title": "miss",
      "first_name": "John",
      "middle_name": "P",
      "last_name": "Doe"
    },
    "address": {
      "city": "New York",
      "country": "SG",
      "line1": "123 5th Avenue",
      "state": "NY",
      "postcode": "10001"
    }
  },
  "mobile_number": "11111222222",
  "postal_address": {
    "city": "New York",
    "country": "SG",
    "line1": "123 5th Avenue",
    "state": "NY",
    "postcode": "10001"
  },
  "type": "INDIVIDUAL",
  "created_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("POST", url, headers=headers, data=payload)

print(response.text)

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n\"email\": \"test123@yopmail.com\",\r\n\"individual\": {\r\n    \"date_of_birth\": \"1990-01-01\",\r\n    \"name\": {\r\n        \"title\": \"miss\",\r\n        \"first_name\": \"John\",\r\n        \"middle_name\":\"P\",\r\n        \"last_name\": \"Doe\"\r\n    },\r\n    \"address\": {\r\n        \"city\": \"New York\",\r\n        \"country\": \"SG\",\r\n        \"line1\": \"123 5th Avenue\",\r\n        \"state\": \"NY\",\r\n        \"postcode\": \"10001\"\r\n    }\r\n},\r\n\"mobile_number\": \"11111222222\",\r\n\"postal_address\": {\r\n    \"city\": \"New York\",\r\n    \"country\": \"SG\",\r\n    \"line1\": \"123 5th Avenue\",\r\n    \"state\": \"NY\",\r\n    \"postcode\": \"10001\"\r\n},\r\n\"type\": \"INDIVIDUAL\",\r\n\"created_by\": \"test\"\r\n}\r\n\r\n\r\n\n\n\n\n\n\n");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v1/card/cardholder")
  .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();

php

<?php
$client = new Client();
$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}}'
];
$body = '{
  "email": "test123@yopmail.com",
  "individual": {
    "date_of_birth": "1990-01-01",
    "name": {
      "title": "miss",
      "first_name": "John",
      "middle_name": "P",
      "last_name": "Doe"
    },
    "address": {
      "city": "New York",
      "country": "SG",
      "line1": "123 5th Avenue",
      "state": "NY",
      "postcode": "10001"
    }
  },
  "mobile_number": "11111222222",
  "postal_address": {
    "city": "New York",
    "country": "SG",
    "line1": "123 5th Avenue",
    "state": "NY",
    "postcode": "10001"
  },
  "type": "INDIVIDUAL",
  "created_by": "test"
}';
$request = new Request('POST', '{{baseUrl}}/zoqq/api/v1/card/cardholder', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "{{baseUrl}}/zoqq/api/v1/card/cardholder");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent("{\r\n\"email\": \"test123@yopmail.com\",\r\n\"individual\": {\r\n    \"date_of_birth\": \"1990-01-01\",\r\n    \"name\": {\r\n        \"title\": \"miss\",\r\n        \"first_name\": \"John\",\r\n        \"middle_name\":\"P\",\r\n        \"last_name\": \"Doe\"\r\n    },\r\n    \"address\": {\r\n        \"city\": \"New York\",\r\n        \"country\": \"SG\",\r\n        \"line1\": \"123 5th Avenue\",\r\n        \"state\": \"NY\",\r\n        \"postcode\": \"10001\"\r\n    }\r\n},\r\n\"mobile_number\": \"11111222222\",\r\n\"postal_address\": {\r\n    \"city\": \"New York\",\r\n    \"country\": \"SG\",\r\n    \"line1\": \"123 5th Avenue\",\r\n    \"state\": \"NY\",\r\n    \"postcode\": \"10001\"\r\n},\r\n\"type\": \"INDIVIDUAL\",\r\n\"created_by\": \"test\"\r\n}\r\n\r\n\r\n\n\n\n\n\n\n", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

{
  "status": "success",
  "message": "Cardholder created successfully.",
  "code": 200,
  "data": [
      {
          "id": "cardholder-id"
      }
  ]
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Get All Cardholders

Endpoint

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

Description

Cardholders are authorized representatives of your business. Two types of cardholders are permitted: Individual and Delegate.

INDIVIDUAL: A cardholder who is a named representative of your business. They can be issued either personalized or non-personalized cards.
DELEGATE: A cardholder assigned only to non-personalized cards. They act as authorized users on behalf of your business. Cards issued to delegate cardholders will be associated with the name of your business.

Cardholders must have completed the name screening process to appear in the results.
This endpoint allows you to retrieve all existing cardholders associated with your business, including their details and status.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card/cardholder' \
--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}}'

Python

import requests
import json

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

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.json())

Java

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/cardholder")
  .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();

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('GET', '{{baseUrl}}/zoqq/api/v1/card/cardholder', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "{{baseUrl}}/zoqq/api/v1/card/cardholder");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

{
    "status": "success",
    "message": "Cardholder fetched successfully",
    "code": 200,
    "data": [
        {
            "id": "cardholder-id",
            "email": "demo@yopmail.com",
            "status": "READY",
            "individual": null,
            "mobile_number": "91-95053039",
            "postal_address": null,
            "type": "DELEGATE",
            "created_by": "test",
            "created_at": "2025-07-10T05:42:45"
        },
        {
            "id": "cardholder-id",
            "email": "testapiair99@yopmail.com",
            "status": "PENDING",
            "individual": {
                "date_of_birth": "1990-01-01",
                "identification": {
                    "country": "US",
                    "expiry_date": "2030-12-31",
                    "number": "ID123456789",
                    "type": "PASSPORT"
                },
                "name": {
                    "title": "miss",
                    "first_name": "John",
                    "middle_name": "singh",
                    "last_name": "Doe"
                },
                "address": {
                    "city": "New York",
                    "country": "SG",
                    "line1": "123 5th Avenue",
                    "state": "NY",
                    "postcode": "10001"
                }
            },
            "mobile_number": "1234567890",
            "postal_address": {
                "city": "New York",
                "country": "SG",
                "line1": "123 5th Avenue",
                "state": "NY",
                "postcode": "10001"
            },
            "type": "INDIVIDUAL",
            "created_by": "test",
            "created_at": "2025-08-08T06:03:12"
        },
        {
            "id": "cardholder-id",
            "email": "test.cardholder@yopmail.com",
            "status": "READY",
            "individual": null,
            "mobile_number": "+65123456789",
            "postal_address": null,
            "type": "DELEGATE",
            "created_by": "awx.test01@yopmail.com",
            "created_at": "2025-07-28T07:45:48"
        }
    ]
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong",
}

Get Cardholder Details

This API allows you to get the cardholder details from the system.

Endpoint

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

Description

This endpoint allows you to retrieve a specific existing cardholder associated with your business, including their details and status.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key for request tracking
x-user-id	string	Yes	User identification key
Content-Type	string	Yes	Must be application/json
Authorization	string	Yes	Bearer token

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Cardholder identifier to get details for

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card/cardholder?id={{CardholderID}}' \
--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}}'

Python

import requests
import json

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

payload = {}
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("GET", url, headers=headers, data=payload)

print(response.text)

Java

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/cardholder?id={{CardholderID}}")
  .method("GET", 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();

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('GET', '{{baseUrl}}/zoqq/api/v1/card/cardholder?id={{CardholderID}}', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "{{baseUrl}}/zoqq/api/v1/card/cardholder?id={{CardholderID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Created

{
  "status": "success",
  "message": "Cardholder fetched successfully",
  "code": 200,
  "data": [
    {
      "id": "cardholder-id",
      "email": "demo@yopmail.com",
      "status": "READY",
      "individual": null,
      "mobile_number": "91-95053039",
      "postal_address": null,
      "type": "DELEGATE",
      "created_by": "test",
      "created_at": "2025-07-10T05:42:45"
    }
  ]
}

400: Error

{
  "code": 400,
  "status": "error",
  "message": "Something went wrong"
}

Update Cardholder

This API updates card holder details including address and contact information.

Endpoint

PATCH {{baseUrl}}/zoqq/api/v3/card/cardholder

Description

This endpoint updates card holder information including physical address, postal address, and contact details.Update a cardholder with selected information. All fields are optional, and only those provided will be updated. If a composite object, e.g. name is provided, then all of its child fields must be provided and valid. Updating the cardholder may re-trigger the name screening process.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description
individual	object	No	Individual details
individual.address	object	No	Physical address of the individual
individual.address.city	string	No	City name
individual.address.country	string	No	Country code (ISO 2-letter)
individual.address.line1	string	No	Street address line 1
individual.address.state	string	No	State or province
individual.address.postcode	string	No	Postal or ZIP code
mobile_number	string	No	Updated mobile number
postal_address	object	No	Mailing/postal address
postal_address.city	string	No	City name
postal_address.country	string	No	Country code (ISO 2-letter)
postal_address.line1	string	No	Street address line 1
postal_address.state	string	No	State or province
postal_address.postcode	string	No	Postal or ZIP code
updated_at	string	No	Timestamp or version of the update (string)
updated_by	string	Yes	Identifier of the user who performed the update

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Cardholder identifier to update

Request Example

cURL

curl --location --request PATCH \
--url '{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}' \
--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 '{
  "individual": {
    "address": {
      "city": "Austin",
      "country": "US",
      "line1": "1234 Elm Street",
      "state": "TX",
      "postcode": "94932"
    }
  },
  "mobile_number": "91-95053039",
  "postal_address": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "5678 Oak Avenue",
    "state": "CA",
    "postcode": "94932"
  }, 
  "updated_at": "57",
  "updated_by": "user"
}'

Python

import requests
import json

url = "{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}"

payload = json.dumps({
  "individual": {
    "address": {
      "city": "Austin",
      "country": "US",
      "line1": "1234 Elm Street",
      "state": "TX",
      "postcode": "94932"
    }
  },
  "mobile_number": "91-95053039",
  "postal_address": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "5678 Oak Avenue",
    "state": "CA",
    "postcode": "94932"
  },
  "updated_at": "57",
  "updated_by": "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("PATCH", url, headers=headers, data=payload)

print(response.text)

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"individual\": {\r\n    \"address\": {\r\n      \"city\": \"Austin\",\r\n      \"country\": \"US\",\r\n      \"line1\": \"1234 Elm Street\",\r\n      \"state\": \"TX\",\r\n      \"postcode\": \"94932\"\r\n    }\r\n  },\r\n  \"mobile_number\": \"91-95053039\",\r\n  \"postal_address\": {\r\n    \"city\": \"Los Angeles\",\r\n    \"country\": \"US\",\r\n    \"line1\": \"5678 Oak Avenue\",\r\n    \"state\": \"CA\",\r\n    \"postcode\": \"94932\"\r\n  }, \r\n  \"updated_at\": \"57\",\r\n  \"updated_by\": \"user\"\r\n}");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}")
  .method("PATCH", 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();

php

<?php
$client = new Client();
$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}}'
];
$body = '{
  "individual": {
    "address": {
      "city": "Austin",
      "country": "US",
      "line1": "1234 Elm Street",
      "state": "TX",
      "postcode": "94932"
    }
  },
  "mobile_number": "91-95053039",
  "postal_address": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "5678 Oak Avenue",
    "state": "CA",
    "postcode": "94932"
  },
  "updated_at": "57",
  "updated_by": "user"
}';
$request = new Request('PATCH', '{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Patch, "{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent("{\r\n  \"individual\": {\r\n    \"address\": {\r\n      \"city\": \"Austin\",\r\n      \"country\": \"US\",\r\n      \"line1\": \"1234 Elm Street\",\r\n      \"state\": \"TX\",\r\n      \"postcode\": \"94932\"\r\n    }\r\n  },\r\n  \"mobile_number\": \"91-95053039\",\r\n  \"postal_address\": {\r\n    \"city\": \"Los Angeles\",\r\n    \"country\": \"US\",\r\n    \"line1\": \"5678 Oak Avenue\",\r\n    \"state\": \"CA\",\r\n    \"postcode\": \"94932\"\r\n  }, \r\n  \"updated_at\": \"57\",\r\n  \"updated_by\": \"user\"\r\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

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

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Delete Cardholder

This API allows you to permanently delete a cardholder from the system.

Endpoint

DELETE {{baseUrl}}/zoqq/api/v3/card/cardholder

Description

Permanently deletes a specified cardholder from the system. This action is irreversible.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key for request tracking
x-user-id	string	Yes	User identification key
Content-Type	string	Yes	Must be application/json
Authorization	string	Yes	Bearer token

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Cardholder Identifier

Request Example

cURL

curl --location --request DELETE \
--url '{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}' \
--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}}'

Python

import requests
import json

url = "{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}"

payload = {}
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("DELETE", url, headers=headers, data=payload)

print(response.text)

Java

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/v3/card/cardholder?id={{CardholderID}}")
  .method("DELETE", 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();

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('DELETE', '{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Delete, "{{baseUrl}}/zoqq/api/v3/card/cardholder?id={{CardholderID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Created

{
  "status": "success",
  "message": "Cardholder deleted successfully.",
  "code": 200
}

400: Error

{
  "code": 400,
  "status": "error",
  "message": "Something went wrong"
}

Create Card

This API creates a new card for a cardholder in the system.

Endpoint

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

Description

The card object represents the resource associated with a card issued by Zoqq. It contains details such as the linked account, embossed name (for physical cards), shipping method and information (for physical cards), and card-based spend controls (e.g., transaction limits, blocked merchant category codes, etc.). The card object also specifies the intended user (e.g., clients, customers, or employees), the form factor (physical or virtual), and the usage type (single-use or multi-use).

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description
card_issuance_action	string	Yes	Card issuance type (NEW, REPLACEMENT)
card_type	string	Yes	Card type (PHYSICAL, VIRTUAL)
card_holder_id	string	Yes	ID of the cardholder
created_by	string	Yes	ID of the user who created the request
request_id	string	Yes	Unique ID for idempotency
program	object	Yes	Program details
program.purpose	string	Yes	Purpose of the card (COMMERCIAL, CONSUMER)
program.type	string	Yes	Type of the card (DEBIT, CREDIT)
authorization_controls	object	Yes	Transaction control configurations
authorization_controls.allowed_transaction_count	string	Yes	SINGLE or MULTIPLE
authorization_controls.transaction_limits	object	Yes	Transaction limits configuration
authorization_controls.transaction_limits.currency	string	Yes	Currency for the transaction limits (USD, etc.)
authorization_controls.transaction_limits.limits	array	Yes	List of limit objects
authorization_controls.transaction_limits.limits[].amount	integer	Yes	Transaction limit amount (> 0)
authorization_controls.transaction_limits.limits[].interval	string	Yes	Interval (PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME)
postal_address	object	Yes	Mailing/postal address required in case of physical card
postal_address.city	string	Yes	City name
postal_address.country	string	Yes	Country code (ISO 2-letter)
postal_address.line1	string	Yes	Street address line 1
postal_address.state	string	Yes	State or province
postal_address.postcode	string	Yes	Postal or ZIP code
is_personalized	boolean	Yes	Determines whether the card should be assigned to a singular individual or to the business with multiple cardholders who are authorized to use the card. Note - only personalized cards can be created as physical and added to digital wallet providers.

Request Example

cURL

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",
    "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
}'

Python

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",
    "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
})
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)

Java

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        \"type\": \"DEBIT\"\r\n      },\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();

php

<?php
$client = new Client();
$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}}'
];
$body = '{
  "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
}';
$request = new Request('POST', '{{baseUrl}}/zoqq/api/v1/card', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "{{baseul}}/zoqq/api/v1/card");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent("{\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        \"type\": \"DEBIT\"\r\n      },\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    }", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

{
  "code": 200,
  "status": "success",
  "message": "",
  "data": {
    "id": "card-id"
  }
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Get All Cards

This API retrieves a list of all cards associated with the authenticated user.

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. Used to retrieve and display a user’s active or inactive cards for review, management, or filtering by type or status in customer portals, dashboards.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by card status (ACTIVE, INACTIVE)
card_type	string	No	Filter by card type (PHYSICAL, VIRTUAL)
limit	integer	No	Number of results per page (default: 20)
offset	integer	No	Pagination offset (default: 0)

Response Parameters

Parameter	Type	Description
code	integer	Response status code
status	string	Response status
message	string	Additional message
data	array	Array of card objects
data[].cardHashId	string	Unique card identifier
data[].cardStatus	string	Card status (ACTIVE/INACTIVE)
data[].maskedCardNumber	string	Masked card number
data[].cardholderId	string	Associated cardholder ID
data[].createdAt	string	Creation timestamp (ISO 8601 format)
data[].updatedAt	string	Last update timestamp (ISO 8601 format)
data[].nameOnCard	string	Name printed on the card
data[].cardType	string	Card type (PHYSICAL/VIRTUAL)
data[].currency	string	Card currency code

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card?status=ACTIVE&card_type=VIRTUAL' \
--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}}'

Python

import requests

url = "{{baseUrl}}/zoqq/api/v1/card"
params = {
    "status": "ACTIVE",
    "card_type": "VIRTUAL"
}

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

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("{{baseUrl}}/zoqq/api/v1/card?status=ACTIVE&card_type=VIRTUAL"))
    .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());

php

<?php
$url = '{{baseUrl}}/zoqq/api/v1/card?status=ACTIVE&card_type=VIRTUAL';

$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}}'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Get,
            RequestUri = new Uri("{{baseUrl}}/zoqq/api/v1/card?status=ACTIVE&card_type=VIRTUAL"),
            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}}" }
            }
        };

        using (var response = await client.SendAsync(request))
        {
            response.EnsureSuccessStatusCode();
            var body = await response.Content.ReadAsStringAsync();
            Console.WriteLine(body);
        }
    }
}

Response Example

200: Success

{
  "code": 200,
  "status": "success",
  "message": "",
  "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"
    }
  ]
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Get All Cards By Cardholder ID

Endpoint

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

Description

This API allows you to retrieve all cards associated with a particular cardholder from the system.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key for request tracking
x-user-id	string	Yes	User identification key
Content-Type	string	Yes	Must be application/json
Authorization	string	Yes	Bearer token

Query Parameters

Parameter	Type	Required	Description
cardholder_id	string	Yes	Cardholder Identifier

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card?cardholder_id={{CardholderID}}' \
--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}}'

Python

import requests
import json

url = "{{baseUrl}}/zoqq/api/v1/card?cardholder_id={{CardholderID}}"

payload = {}
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("GET", url, headers=headers, data=payload)

print(response.text)

Java

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?cardholder_id={{CardholderID}}")
  .method("GET", 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();

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('GET', '{{baseUrl}}/zoqq/api/v1/card?cardholder_id={{CardholderID}}', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "{{baseUrl}}/zoqq/api/v1/card?cardholder_id={{CardholderID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Created

{
  "status": "success",
  "message": "Card fetched successfully",
  "code": 200,
  "data": [
    {
      "card_hash_id": "card-hash-id",
      "card_status": "ACTIVE",
      "masked_card_number": "************1163",
      "cardholder_id": "cardholder_id",
      "created_at": "2025-08-13T08:29:04",
      "updated_at": null,
      "name_on_card": "test",
      "card_type": "VIRTUAL",
      "currency": "USD",
      "postal_address": null
    },
    {
      "card_hash_id": "card-hash-id",
      "card_status": "ACTIVE",
      "masked_card_number": "************0647",
      "cardholder_id": "cardholder_id",
      "created_at": "2025-08-13T07:19:17",
      "updated_at": null,
      "name_on_card": "10210",
      "card_type": "VIRTUAL",
      "currency": "USD",
      "postal_address": null
    }
  ]
}

400: Error

{
  "code": 400,
  "status": "error",
  "message": "Something went wrong"
}

Get Card Details

This API retrieves sensitive card details including card number, CVV, and expiration information.

Endpoint

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

Description

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

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Card ID to retrieve details for

Request Example

cURL

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}}'

Python

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

Java

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}}")
    .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());

php

<?php
$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}}'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Get,
            RequestUri = new Uri("{{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}}" }
            }
        };

        using (var response = await client.SendAsync(request))
        {
            response.EnsureSuccessStatusCode();
            var body = await response.Content.ReadAsStringAsync();
            Console.WriteLine(body);
        }
    }
}

Response Example

200: Success

{
  "status": "success",
  "message": "Card detail fetched successfully.",
  "code": 200,
  "data": [
    {
      "alert_settings": {
        "low_remaining_transaction_limit": {
            "enabled": true,
            "percent": 10
        }
      },
      "all_card_versions": [
        {
            "card_number": "************8656",
            "card_status": "ACTIVE",
            "card_version": 1,
            "created_at": "2025-08-08T07:42:27.059+0000"
        }
      ],
      "authorization_controls": {
        "active_from": "2025-05-01T00:00:00.000+00:00",
        "active_to": "2025-12-31T23:59:59.000+00:00",
        "allowed_currencies": [
            "USD",
            "EUR",
            "INR"
        ],
        "allowed_merchant_categories": [
            "5411",
            "5732",
            "5999"
        ],
        "allowed_transaction_count": "MULTIPLE",
        "blocked_transaction_usages": [],
        "transaction_limits": {
          "currency": "USD",
          "limits": [
            {
              "amount": 1,
              "interval": "DAILY"
            },
            {
              "amount": 10000.0,
              "interval": "PER_TRANSACTION"
            }
          ]
        }
      },
      "brand": "VISA",
      "card_id": "card-id",
      "card_number": "************8656",
      "card_status": "ACTIVE",
      "card_version": 1,
      "cardholder_id": "cardholder-id",
      "created_at": "2025-08-08T07:42:27.059+0000",
      "created_by": "cardholder-id",
      "delivery_details": {
        "delivery_mode": "MAIL",
        "delivery_vendor": "DHL",
        "status": "PRINTED",
        "tracked": true,
        "tracking_link": "tracking-link",
        "tracking_number": "ABCD123456",
        "updated_at": "2025-09-04T00:00:00.000+0000"
      },
      "form_factor": "VIRTUAL",
      "is_personalized": false,
      "name_on_card": "user's name",
      "nick_name": "null",
      "program": {
        "purpose": "COMMERCIAL",
        "type": "DEBIT"
      },
      "purpose": "BUSINESS_EXPENSES",
      "request_id": "user728",
      "updated_at": "2025-09-04T06:01:35.599+0000"
    }
  ]
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Activate Card

This API activates an inactive card in the system.

Endpoint

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

Description

This endpoint activates a specific card (physical or virtual) associated with the user by updating its status to ACTIVE. Activation typically requires the card’s unique identifier and any necessary verification parameters, depending on the program’s setup. Used when a new card is issued and needs to be activated by the user before use. This is typically triggered via a user action in a web portal to begin using the card for transactions.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the card to activate

Request Example

cURL

curl --location --request POST \
--url '{{baseUrl}}/zoqq/api/v3/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}}'

Python

import requests
import json

url = "{{baseUrl}}/zoqq/api/v3/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)

Java

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/v3/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();

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('POST', '{{baseUrl}}/zoqq/api/v3/card/activate?id={{CardID}}', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "{{baseUrl}}/zoqq/api/v3/card/activate?id={{CardID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

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

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Update Card

This API updates card details including authorization controls and status.

Endpoint

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

Description

This endpoint updates attributes of an existing card, such as its status (e.g., block, unblock), name on the card, or other modifiable fields, depending on the program’s permissions. Only specified fields are updated. Used to perform updates on a card post-issuance—for example, blocking a card due to suspicious activity, unblocking upon user request, or correcting cardholder details

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description
card_status	string	No	Card status — must be one of ACTIVE, INACTIVE, CLOSED
currency	string	No	Currency for the card (e.g., USD, EUR)
transaction_limits	array of objects	No	List of transaction limits
transaction_limits[].type	string	Yes (if present)	Type of limit — one of PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME
transaction_limits[].value	integer	Yes (if present)	Numerical value of the limit
authorization_controls	object	No	Controls for restricting card authorization
authorization_controls.active_from	string (ISO 8601)	No	Start date-time from which card is active (YYYY-MM-DDTHH:mm:ssZ)
authorization_controls.active_to	string (ISO 8601)	No	End date-time until which card remains active
authorization_controls.allowed_currencies	array of strings	No	Allowed currencies for card transactions (e.g., ["USD", "EUR"])
authorization_controls.allowed_merchant_categories	array of strings	No	Allowed merchant category codes (4-digit MCCs)
authorization_controls.transaction_scope	string	No	Type of transactions allowed — e.g., ALL_TRANSACTIONS, ONLINE_TRANSACTION, etc.
authorization_controls.usage_scope	string	No	Geographic usage restriction — one of ALL, INTERNATIONAL, DOMESTIC

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Card ID to update

Request Example

cURL

curl --location --request PATCH \
--url '{{baseUrl}}/zoqq/api/v3/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"],
    "transaction_scope": "ONLINE_TRANSACTION",
    "usage_scope": "INTERNATIONAL"
  },
"updated_by": "test"
}'

Python

import requests
import json

url = "{{baseUrl}}/zoqq/api/v3/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"
    ],
    "transaction_scope": "ONLINE_TRANSACTION",
    "usage_scope": "INTERNATIONAL"
  },
  "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)

Java

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    \"transaction_scope\": \"ONLINE_TRANSACTION\",\n    \"usage_scope\": \"INTERNATIONAL\"\n  },\n \"updated_by\": \"test\"\n} ");
Request request = new Request.Builder()
  .url("{{baseUrl}}/zoqq/api/v3/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();

php

<?php
$client = new Client();
$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}}'
];
$body = '{
  "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"
    ],
    "transaction_scope": "ONLINE_TRANSACTION",
    "usage_scope": "INTERNATIONAL"
  },
  "updated_by": "test"
}';
$request = new Request('PATCH', '{{baseUrl}}/zoqq/api/v3/card?id={{CardID}}', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Patch, "{{baseUrl}}/zoqq/api/v3/card?id={{CardID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent("{\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    \"transaction_scope\": \"ONLINE_TRANSACTION\",\n    \"usage_scope\": \"INTERNATIONAL\"\n  },\n \"updated_by\": \"test\"\n} ", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

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

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Get Card Limit

This API retrieves the current transaction limits and other relevant details for a specific card.

Endpoint

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

Description

This endpoint returns the current transaction limits and remaining amounts for a specific card, including both purchase and cash withdrawal limits.

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Card ID to retrieve limits for
currency	string	No	Filter by specific currency

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/zoqq/api/v1/card/limit?id={{CardID}}&currency=USD' \
--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}}'

Python

import requests

url = "{{baseUrl}}/zoqq/api/v1/card/limit"
params = {
    "id": "{{CardID}}",
    "currency": "USD"
}

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

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("{{baseUrl}}/zoqq/api/v1/card/limit?id={{CardID}}&currency=USD"))
    .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());

php

<?php

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

$payload = json_encode([
    "card_status" => "INACTIVE",
    "currency" => "USD",
    "transaction_limits" => [
        [
            "type" => "DAILY",
            "value" => 1
        ]
    ]
]);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: {{Shared X-API key By Zoqq}}",
    "x-product-id: {{Shared ProductID By Zoqq}}",
    "x-request-id: {{IdempotencyKey}}",
    "x-user-id: {{UserID}}",
    "Authorization: Bearer {{AccessToken}}"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var client = new HttpClient();

        var request = new HttpRequestMessage(HttpMethod.Patch, "{{baseUrl}}/zoqq/api/v1/card");
        request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
        request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
        request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
        request.Headers.Add("x-user-id", "{{UserID}}");
        request.Headers.Add("Content-Type", "application/json");
        request.Headers.Add("Authorization", "Bearer {{AccessToken}}");

        var json = @"
        {
            ""card_status"": ""INACTIVE"",
            ""currency"": ""USD"",
            ""transaction_limits"": [
                {
                    ""type"": ""DAILY"",
                    ""value"": 1
                }
            ]
        }";

        request.Content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = await client.SendAsync(request);
        string result = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Response: {response.StatusCode}");
        Console.WriteLine(result);
    }
}

Response Example

200: Success

{
"code": 200
"status": "success",
"message": "",
"data": [
    {
      "currency": "USD",
      "limits": [
        {
          "amount": 20000.00,
          "interval": "ALL_TIME",
          "remaining": 20000.00
        },
        {
          "amount": 10000.00,
          "interval": "PER_TRANSACTION",
          "remaining": 10000.00
        }
      ]
    }
  ]
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}

Get Card Transactions

This API retrieves transaction history for a specific card.

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

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Shared ProductID By Zoqq
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

Query Parameters

Parameter	Type	Required	Description
id	string	Yes	Card ID to retrieve transactions for
limit	integer	No	Number of transactions to return (default: 20)
offset	integer	No	Pagination offset (default: 0)
start_date	string	No	Filter transactions from this date (YYYY-MM-DD)
end_date	string	No	Filter transactions to this date (YYYY-MM-DD)
status	string	No	Filter by transaction status (APPROVED, DECLINED, etc.)

Request Example

cURL

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}}'

Python

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)

Java

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

php

<?php
$client = new Client();
$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}}'
];
$request = new Request('GET', '{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "{{baseUrl}}/zoqq/api/v1/card/transaction?id={{CardID}}");
request.Headers.Add("x-api-key", "{{Shared X-API key By Zoqq}}");
request.Headers.Add("x-request-id", "{{IdempotencyKey}}");
request.Headers.Add("x-product-id", "{{Shared ProductID By Zoqq}}");
request.Headers.Add("x-user-id", "{{UserID}}");
request.Headers.Add("Authorization", "Bearer {{AccessToken}}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response Example

200: Success

{
  "code": 200,
  "status": "success",
  "message": "",
  "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"
      }
    ]
  }
}

400: Error

{
  "code": 400,
  "status": "Error",
  "message": "Something went wrong"
}