Create Card

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "card_currency": "USD",
  "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_limit": 2100.02,
  "name_on_card": "MARSHALL HU",
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
  "spending_controls": [
    {
      "amount": 100.03,
      "interval": "PER_TRANSACTION"
    }
  ],
  "risk_controls": {
    "enable_3ds": "Y",
    "allow_3ds_transactions": "Y",
    "allowed_mcc": null,
    "blocked_mcc": [
      "5999",
      "6011"
    ]
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "usage_type": "NORMAL",
  "auto_cancel_trigger": "ON_AUTH",
  "expiry_at": "2026-03-19T18:46:43+08:00",
  "cardholder_required_fields": {
    "email": "demo@example.com",
    "first_name": "Emily",
    "last_name": "Toy",
    "country_code": "SG",
    "phone_number": "86683306",
    "date_of_birth": "1990-01-01",
    "gender": "MALE",
    "nationality": "SG"
  }
}
'

import requests

url = "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards"

payload = {
    "card_currency": "USD",
    "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "card_limit": 2100.02,
    "name_on_card": "MARSHALL HU",
    "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
    "spending_controls": [
        {
            "amount": 100.03,
            "interval": "PER_TRANSACTION"
        }
    ],
    "risk_controls": {
        "enable_3ds": "Y",
        "allow_3ds_transactions": "Y",
        "allowed_mcc": None,
        "blocked_mcc": ["5999", "6011"]
    },
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    },
    "usage_type": "NORMAL",
    "auto_cancel_trigger": "ON_AUTH",
    "expiry_at": "2026-03-19T18:46:43+08:00",
    "cardholder_required_fields": {
        "email": "demo@example.com",
        "first_name": "Emily",
        "last_name": "Toy",
        "country_code": "SG",
        "phone_number": "86683306",
        "date_of_birth": "1990-01-01",
        "gender": "MALE",
        "nationality": "SG"
    }
}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "x-auth-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    'x-auth-token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    card_currency: 'USD',
    card_product_id: '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    card_limit: 2100.02,
    name_on_card: 'MARSHALL HU',
    cardholder_id: '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    card_art_id: '01KD52BKQWDMFF63R1NNQN7A79',
    spending_controls: [{amount: 100.03, interval: 'PER_TRANSACTION'}],
    risk_controls: {
      enable_3ds: 'Y',
      allow_3ds_transactions: 'Y',
      allowed_mcc: null,
      blocked_mcc: ['5999', '6011']
    },
    metadata: {key1: 'value1', key2: 'value2'},
    usage_type: 'NORMAL',
    auto_cancel_trigger: 'ON_AUTH',
    expiry_at: '2026-03-19T18:46:43+08:00',
    cardholder_required_fields: {
      email: 'demo@example.com',
      first_name: 'Emily',
      last_name: 'Toy',
      country_code: 'SG',
      phone_number: '86683306',
      date_of_birth: '1990-01-01',
      gender: 'MALE',
      nationality: 'SG'
    }
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/issuing/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'card_currency' => 'USD',
    'card_product_id' => '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    'card_limit' => 2100.02,
    'name_on_card' => 'MARSHALL HU',
    'cardholder_id' => '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    'card_art_id' => '01KD52BKQWDMFF63R1NNQN7A79',
    'spending_controls' => [
        [
                'amount' => 100.03,
                'interval' => 'PER_TRANSACTION'
        ]
    ],
    'risk_controls' => [
        'enable_3ds' => 'Y',
        'allow_3ds_transactions' => 'Y',
        'allowed_mcc' => null,
        'blocked_mcc' => [
                '5999',
                '6011'
        ]
    ],
    'metadata' => [
        'key1' => 'value1',
        'key2' => 'value2'
    ],
    'usage_type' => 'NORMAL',
    'auto_cancel_trigger' => 'ON_AUTH',
    'expiry_at' => '2026-03-19T18:46:43+08:00',
    'cardholder_required_fields' => [
        'email' => 'demo@example.com',
        'first_name' => 'Emily',
        'last_name' => 'Toy',
        'country_code' => 'SG',
        'phone_number' => '86683306',
        'date_of_birth' => '1990-01-01',
        'gender' => 'MALE',
        'nationality' => 'SG'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-auth-token: <api-key>",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards"

	payload := strings.NewReader("{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("x-auth-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v1/issuing/cards")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.uqpaytech.com/api/v1/issuing/cards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "create_time": "2024-03-21T17:17:32+08:00",
  "card_status": "ACTIVE",
  "risk_controls": {
    "enable_3ds": "Y",
    "allow_3ds_transactions": "Y",
    "allowed_mcc": null,
    "blocked_mcc": [
      "5999",
      "6011"
    ]
  },
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "cardholder_created": true,
  "cardholder_status": "SUCCESS",
  "verification_status": "UNDER_REVIEW",
  "kyc_method": "SUMSUB_REDIRECT",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_4dwsbDuDbpJsMgou",
  "idv_url_expires_at": "2026-04-25T17:26:50+08:00",
  "message": "<string>"
}

Card Lifecycle

Create Card

创建一张卡片并将其签发给持卡人。

支持两种调用模式：

传统模式 —— 传入 cardholder_id，将卡片签发给已存在的持卡人。可选传入 cardholder_required_fields，补充该卡产品所需但缺失的持卡人数据。
一步模式 —— 省略 cardholder_id，并传入完整的 cardholder_required_fields 块。系统在单次请求中同时创建持卡人和卡片。完整对接流程参见一步开卡。

POST

issuing

cards

Create Card

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "card_currency": "USD",
  "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_limit": 2100.02,
  "name_on_card": "MARSHALL HU",
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
  "spending_controls": [
    {
      "amount": 100.03,
      "interval": "PER_TRANSACTION"
    }
  ],
  "risk_controls": {
    "enable_3ds": "Y",
    "allow_3ds_transactions": "Y",
    "allowed_mcc": null,
    "blocked_mcc": [
      "5999",
      "6011"
    ]
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "usage_type": "NORMAL",
  "auto_cancel_trigger": "ON_AUTH",
  "expiry_at": "2026-03-19T18:46:43+08:00",
  "cardholder_required_fields": {
    "email": "demo@example.com",
    "first_name": "Emily",
    "last_name": "Toy",
    "country_code": "SG",
    "phone_number": "86683306",
    "date_of_birth": "1990-01-01",
    "gender": "MALE",
    "nationality": "SG"
  }
}
'

import requests

url = "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards"

payload = {
    "card_currency": "USD",
    "card_product_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "card_limit": 2100.02,
    "name_on_card": "MARSHALL HU",
    "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
    "spending_controls": [
        {
            "amount": 100.03,
            "interval": "PER_TRANSACTION"
        }
    ],
    "risk_controls": {
        "enable_3ds": "Y",
        "allow_3ds_transactions": "Y",
        "allowed_mcc": None,
        "blocked_mcc": ["5999", "6011"]
    },
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    },
    "usage_type": "NORMAL",
    "auto_cancel_trigger": "ON_AUTH",
    "expiry_at": "2026-03-19T18:46:43+08:00",
    "cardholder_required_fields": {
        "email": "demo@example.com",
        "first_name": "Emily",
        "last_name": "Toy",
        "country_code": "SG",
        "phone_number": "86683306",
        "date_of_birth": "1990-01-01",
        "gender": "MALE",
        "nationality": "SG"
    }
}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "x-auth-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    'x-auth-token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    card_currency: 'USD',
    card_product_id: '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    card_limit: 2100.02,
    name_on_card: 'MARSHALL HU',
    cardholder_id: '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    card_art_id: '01KD52BKQWDMFF63R1NNQN7A79',
    spending_controls: [{amount: 100.03, interval: 'PER_TRANSACTION'}],
    risk_controls: {
      enable_3ds: 'Y',
      allow_3ds_transactions: 'Y',
      allowed_mcc: null,
      blocked_mcc: ['5999', '6011']
    },
    metadata: {key1: 'value1', key2: 'value2'},
    usage_type: 'NORMAL',
    auto_cancel_trigger: 'ON_AUTH',
    expiry_at: '2026-03-19T18:46:43+08:00',
    cardholder_required_fields: {
      email: 'demo@example.com',
      first_name: 'Emily',
      last_name: 'Toy',
      country_code: 'SG',
      phone_number: '86683306',
      date_of_birth: '1990-01-01',
      gender: 'MALE',
      nationality: 'SG'
    }
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/issuing/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'card_currency' => 'USD',
    'card_product_id' => '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    'card_limit' => 2100.02,
    'name_on_card' => 'MARSHALL HU',
    'cardholder_id' => '7c4ff2cd-1bf6-4aaa-bf16-266771425011',
    'card_art_id' => '01KD52BKQWDMFF63R1NNQN7A79',
    'spending_controls' => [
        [
                'amount' => 100.03,
                'interval' => 'PER_TRANSACTION'
        ]
    ],
    'risk_controls' => [
        'enable_3ds' => 'Y',
        'allow_3ds_transactions' => 'Y',
        'allowed_mcc' => null,
        'blocked_mcc' => [
                '5999',
                '6011'
        ]
    ],
    'metadata' => [
        'key1' => 'value1',
        'key2' => 'value2'
    ],
    'usage_type' => 'NORMAL',
    'auto_cancel_trigger' => 'ON_AUTH',
    'expiry_at' => '2026-03-19T18:46:43+08:00',
    'cardholder_required_fields' => [
        'email' => 'demo@example.com',
        'first_name' => 'Emily',
        'last_name' => 'Toy',
        'country_code' => 'SG',
        'phone_number' => '86683306',
        'date_of_birth' => '1990-01-01',
        'gender' => 'MALE',
        'nationality' => 'SG'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-auth-token: <api-key>",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards"

	payload := strings.NewReader("{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("x-auth-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v1/issuing/cards")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.uqpaytech.com/api/v1/issuing/cards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"card_currency\": \"USD\",\n  \"card_product_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_limit\": 2100.02,\n  \"name_on_card\": \"MARSHALL HU\",\n  \"cardholder_id\": \"7c4ff2cd-1bf6-4aaa-bf16-266771425011\",\n  \"card_art_id\": \"01KD52BKQWDMFF63R1NNQN7A79\",\n  \"spending_controls\": [\n    {\n      \"amount\": 100.03,\n      \"interval\": \"PER_TRANSACTION\"\n    }\n  ],\n  \"risk_controls\": {\n    \"enable_3ds\": \"Y\",\n    \"allow_3ds_transactions\": \"Y\",\n    \"allowed_mcc\": null,\n    \"blocked_mcc\": [\n      \"5999\",\n      \"6011\"\n    ]\n  },\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"usage_type\": \"NORMAL\",\n  \"auto_cancel_trigger\": \"ON_AUTH\",\n  \"expiry_at\": \"2026-03-19T18:46:43+08:00\",\n  \"cardholder_required_fields\": {\n    \"email\": \"demo@example.com\",\n    \"first_name\": \"Emily\",\n    \"last_name\": \"Toy\",\n    \"country_code\": \"SG\",\n    \"phone_number\": \"86683306\",\n    \"date_of_birth\": \"1990-01-01\",\n    \"gender\": \"MALE\",\n    \"nationality\": \"SG\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "create_time": "2024-03-21T17:17:32+08:00",
  "card_status": "ACTIVE",
  "risk_controls": {
    "enable_3ds": "Y",
    "allow_3ds_transactions": "Y",
    "allowed_mcc": null,
    "blocked_mcc": [
      "5999",
      "6011"
    ]
  },
  "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
  "cardholder_created": true,
  "cardholder_status": "SUCCESS",
  "verification_status": "UNDER_REVIEW",
  "kyc_method": "SUMSUB_REDIRECT",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_4dwsbDuDbpJsMgou",
  "idv_url_expires_at": "2026-04-25T17:26:50+08:00",
  "message": "<string>"
}

授权

x-auth-token

string

header

必填

由 UQPay 提供的登录 API Token。

请求头

x-on-behalf-of

string

指定代表哪个子账户发起请求。应设置为 account_id，该值可通过 List Connected Accounts 接口获取。若省略或为空，则请求以主账户身份执行。更多信息参见关联账户。

x-idempotency-key

string<uuid>

必填

用于维持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败的情况下保持数据一致性。

请求体

application/json

card_currency

enum<string>

必填

卡币种。

可用选项:

SGD,

USD,

XUSD

示例:

"USD"

card_product_id

string

必填

卡产品的唯一标识符。

示例:

"7c4ff2cd-1bf6-4aaa-bf16-266771425011"

card_limit

number

分配给该卡片的总信用额度，币种参见 card_currency。这不是累计余额，而是类似信用卡的固定信用额度。

各卡产品的字段行为：

Business Mastercard 和 Personal Visa：创建卡片时 card_limit 为必填，且必须大于或等于 0.01。
Business Visa：card_limit 为可选。
- 若省略，系统默认 card_limit 为 0。
- 若提供，取值必须大于或等于 0，最多两位小数。不允许负值。

完整能力矩阵参见卡产品。

必填范围: x >= 0

示例:

2100.02

name_on_card

string

卡片上显示的持卡人姓名。当 Secure iFrame 渲染持卡人姓名（cardholder_name=true）时，此值作为默认值；若省略，iframe 回退到持卡人记录中的 first_name + last_name。

Maximum string length: 26

示例:

"MARSHALL HU"

cardholder_id

string<uuid>

要签发卡片的持卡人的唯一标识符。

必须提供 cardholder_id 或完整的 cardholder_required_fields 块之一。当省略 cardholder_id 时，系统使用 cardholder_required_fields 中的值内联创建新持卡人。参见一步开卡。

示例:

"7c4ff2cd-1bf6-4aaa-bf16-266771425011"

card_art_id

string

应用到新卡片的卡面。当省略时，卡片使用发卡账户的默认卡面——默认值的解析方式参见卡面。

该值必须是发卡账户可用的卡面。可通过列出卡面查询可用卡面。

示例:

"01KD52BKQWDMFF63R1NNQN7A79"

spending_controls

object[]

控制该卡片消费的规则。

Show child attributes

risk_controls

object

用户自定义的风控设置。

支持的配置取决于卡产品。能力矩阵参见卡产品。

Show child attributes

metadata

object

任意键值对象。最大长度 = 3200 字节。必须是有效的 JSON 数据。

Show child attributes

示例:

{ "key1": "value1", "key2": "value2" }

usage_type

enum<string>

默认值:NORMAL

表示卡片是标准可复用卡还是一次性卡。

NORMAL - 可用于多笔交易的标准卡。
ONE_TIME - 一次性卡，在 auto_cancel_trigger 定义的首次交易事件后自动注销。

可用选项:

NORMAL,

ONE_TIME

示例:

"NORMAL"

auto_cancel_trigger

enum<string>

定义触发 ONE_TIME 卡自动注销的交易事件。当 usage_type 为 ONE_TIME 时必填。

ON_AUTH - 卡片在首次授权通过后立即注销。该卡上后续的授权请求都将被拒绝。
ON_CAPTURE - 卡片在首笔交易请款（结算）成功后注销，允许完成一个完整的授权与请款周期。

可用选项:

ON_AUTH,

ON_CAPTURE

示例:

"ON_AUTH"

expiry_at

string<date-time>

卡片的绝对过期日期和时间。如果在此时间之前卡片未因首次交易事件被注销，则会自动注销，任何未使用的余额都会被释放。

示例:

"2026-03-19T18:46:43+08:00"

cardholder_required_fields

object

创建卡片时提供的持卡人信息。

传统模式（提供 cardholder_id）：可选；此处提供的字段用于在签发卡片前补全缺失的持卡人数据。
一步模式（省略 cardholder_id）：必填，且必须包含完整的持卡人创建字段（email、first_name、last_name、country_code、phone_number）。系统会内联创建持卡人。

Show child attributes

响应

200 - application/json

成功创建卡片。

card_id

string

必填

卡片的唯一标识符。

示例:

"c0cef051-29c5-4796-b86a-cd5b684bfad7"

card_order_id

string

必填

卡订单的 ID。

示例:

"c0cef051-29c5-4796-b86a-cd5ee34bfad7"

create_time

string

必填

对象的创建时间。

示例:

"2024-03-21T17:17:32+08:00"

card_status

enum<string>

必填

卡片状态枚举。更多信息参见卡生命周期与状态指南。

PENDING：创建卡片的请求已收到，正在审核中。
ACTIVE：创建卡片的请求成功，卡片可以使用。
FROZEN：所有进入的授权请求都将被拒绝。卡片可以重新激活以接受新的授权。
BLOCKED：因可疑活动，卡片被 UQPAY 锁定。
PRE_CANCEL：卡片已被安排注销，处于等待期，期间所有进入的授权请求都将被拒绝。等待期结束后转为 CANCELLED。
CANCELLED：卡片无法再从此状态重新激活，所有进入的授权请求都将被永久拒绝。
LOST：卡片已向 UQPAY 报失。
STOLEN：卡片已向 UQPAY 报被盗。
FAILED：使用创建卡片创建卡片的请求失败。

可用选项:

PENDING,

ACTIVE,

FROZEN,

BLOCKED,

PRE_CANCEL,

CANCELLED,

LOST,

STOLEN,

FAILED

示例:

"ACTIVE"

order_status

enum<string>

必填

此字段包含请求处理后的状态。

PENDING - 订单请求的初始状态。
PROCESSING - 此状态将通过 webhooks 通知。
SUCCESS - 订单请求的最终状态为成功。
FAILED - 订单请求的最终状态为失败。

可用选项:

PENDING,

PROCESSING,

SUCCESS,

FAILED

risk_controls

object

应用到卡片的风控设置。回显自请求；若未提供，则填充为卡产品的默认值。

Show child attributes

cardholder_id

string<uuid>

持卡人的唯一标识符。在一步模式下，这是新创建的持卡人——请保存此值以便后续引用该持卡人。

示例:

"7c4ff2cd-1bf6-4aaa-bf16-266771425011"

cardholder_created

boolean

当本次请求内联创建了新持卡人时为 true。否则省略。

示例:

true

cardholder_status

enum<string>

默认值:SUCCESS

持卡人的状态。

可用选项:

FAILED,

PENDING,

SUCCESS,

INCOMPLETE

verification_status

enum<string>

持卡人的 KYC 验证结果。当补充字段触发了 KYC 处理时返回。

可用选项:

VERIFIED,

UNDER_REVIEW,

ACTION_REQUIRED

示例:

"UNDER_REVIEW"

kyc_method

enum<string>

回显已应用的 KYC 验证方式。当请求中提供了 cardholder_required_fields.kyc_verification 时返回。

THIRD_PARTY - 使用了商户提供的 KYC 凭证。
SUMSUB_REDIRECT - 持卡人被重定向到 Sumsub 完成 IDV。

可用选项:

THIRD_PARTY,

SUMSUB_REDIRECT

示例:

"SUMSUB_REDIRECT"

idv_verification_url

string<uri>

持卡人必须访问以完成身份验证的 IDV 验证 URL。仅当 kyc_method 为 SUMSUB_REDIRECT 时返回。

示例:

"https://in.sumsub.com/websdk/p/sbx_4dwsbDuDbpJsMgou"

idv_url_expires_at

string<date-time>

idv_verification_url 的过期时间。仅当 kyc_method 为 SUMSUB_REDIRECT 时返回。

示例:

"2026-04-25T17:26:50+08:00"

message

string

当因 KYC 要求导致创建卡片被阻止或挂起时的提示信息（如 KYC 不足、字段缺失）。

List cards Retrieve card