Set or Reset Virtual Card PIN

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/manage/pin \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "card_id": "630be6bd-2652-4faa-9f3d-2c51cee0b820",
  "type": "SET",
  "pin": "1234",
  "old_pin": "5678"
}
'

import requests

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

payload = {
    "card_id": "630be6bd-2652-4faa-9f3d-2c51cee0b820",
    "type": "SET",
    "pin": "1234",
    "old_pin": "5678"
}
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_id: '630be6bd-2652-4faa-9f3d-2c51cee0b820',
    type: 'SET',
    pin: '1234',
    old_pin: '5678'
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/manage/pin', 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/manage/pin",
  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_id' => '630be6bd-2652-4faa-9f3d-2c51cee0b820',
    'type' => 'SET',
    'pin' => '1234',
    'old_pin' => '5678'
  ]),
  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/manage/pin"

	payload := strings.NewReader("{\n  \"card_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\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/manage/pin")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"card_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\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 PIN

Set or Reset Virtual Card PIN

Business Mastercard only

Set or reset the PIN on a Standard virtual card.

type: SET — set the PIN for the first time. Fails if the card already has a PIN; use RESET instead.
type: RESET — change the PIN. The request must carry old_pin, and it must match the card’s current PIN.

No forgot-PIN flow. RESET always requires the current PIN via old_pin. If the current PIN is lost, the PIN cannot be reset through this API — contact UQPAY for assistance.

Standard virtual cards only. This endpoint does not apply to physical cards — use Reset Card PIN to manage physical card PINs.

Asynchronous processing

The synchronous response only confirms the request was accepted and returns the PIN operation order (card_id, card_order_id, create_time). Repeated requests with the same x-idempotency-key return the same result without re-processing. A card can have only one PIN operation in flight at a time — submitting another SET / RESET request while one is still being processed is rejected.

POST

issuing

cards

manage

Set or Reset Virtual Card PIN

curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/manage/pin \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "card_id": "630be6bd-2652-4faa-9f3d-2c51cee0b820",
  "type": "SET",
  "pin": "1234",
  "old_pin": "5678"
}
'

import requests

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

payload = {
    "card_id": "630be6bd-2652-4faa-9f3d-2c51cee0b820",
    "type": "SET",
    "pin": "1234",
    "old_pin": "5678"
}
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_id: '630be6bd-2652-4faa-9f3d-2c51cee0b820',
    type: 'SET',
    pin: '1234',
    old_pin: '5678'
  })
};

fetch('https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/manage/pin', 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/manage/pin",
  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_id' => '630be6bd-2652-4faa-9f3d-2c51cee0b820',
    'type' => 'SET',
    'pin' => '1234',
    'old_pin' => '5678'
  ]),
  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/manage/pin"

	payload := strings.NewReader("{\n  \"card_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\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/manage/pin")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-auth-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"card_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_id\": \"630be6bd-2652-4faa-9f3d-2c51cee0b820\",\n  \"type\": \"SET\",\n  \"pin\": \"1234\",\n  \"old_pin\": \"5678\"\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"
}

Authorizations

x-auth-token

string

header

required

The API token for login provided by UQPay.

Headers

x-on-behalf-of

string

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts endpoint. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-key

string<uuid>

required

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

Body

application/json

card_id

string<uuid>

required

Unique identifier for the card. Must be a Standard virtual card.

Example:

"630be6bd-2652-4faa-9f3d-2c51cee0b820"

type

enum<string>

required

The PIN operation to perform.

SET - Set the card's PIN for the first time. Rejected if the card already has a PIN.
RESET - Change the card's PIN. Requires old_pin.

Available options:

SET,

RESET

Example:

"SET"

string

required

The new PIN for the card. Must be exactly 4 numeric digits.

Required string length: 4

Pattern: ^\d{4}$

Example:

"1234"

old_pin

string

The card's current PIN. Required when type is RESET and must match the PIN currently set on the card, otherwise the operation fails. Ignored when type is SET.

Required string length: 4

Pattern: ^\d{4}$

Example:

"5678"

Response

200 - application/json

PIN operation request accepted.

card_id

string

required

Unique identifier for the card.

Example:

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

card_order_id

string

required

ID of the card order.

Example:

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

create_time

string

required

Create time at which the object was created.

Example:

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

Reset pin List card arts