> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/card-issuance/v1.6/api-reference/reset-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.
## OpenAPI
````yaml /card-issuance/v1.6/issuing.yaml post /v1/issuing/cards/manage/pin
openapi: 3.0.2
info:
title: Issuing API
version: 0.0.1
description: >
UQPAY Issuing API allows you to issue virtual cards, manage cardholders, and
monitor card transactions.
## What you can do
- Create and manage virtual cards (issue, activate, freeze, cancel)
- Onboard and verify cardholders with KYC
- Set spending limits and card controls
- Recharge and withdraw card balances
- Query card transactions and account balances
- Transfer funds between issuing accounts
- Generate and download reports
## Authentication
All requests require a valid auth token obtained via the [Access
Token](/account-center/v1.6/api-reference/access-token) endpoint. Include
the token in the `x-auth-token` header.
## Idempotency
POST requests support the `x-idempotency-key` header to safely retry without
creating duplicate resources.
contact:
name: UQPAY Support Team
url: https://www.uqpay.com/support
email: support@uqpay.com
license:
name: Proprietary
url: https://www.uqpay.com/legal/api-terms
termsOfService: https://www.uqpay.com/legal/terms
x-api-id: uqpay-issuing-api-v1.6.0
x-categories:
- Card Issuing
- Transaction Processing
x-features:
- Virtual Card Issuance
- Real-time Processing
- Webhook Notifications
- Comprehensive Reporting
- Transaction Monitoring
servers:
- url: https://api-sandbox.uqpaytech.com/api
description: Sandbox base URL.
- url: https://api.uqpay.com/api
description: Production base URL.
security: []
tags:
- name: Card Lifecycle
description: >-
Create cards and manage their full lifecycle — issue, retrieve, update,
activate, assign, and change status.
- name: Card Secure Data
description: >-
Access sensitive card data (PAN, CVV) through the PCI-compliant endpoint
or a tokenized iframe. Availability depends on your PCI status, not the
card product.
- name: Card Funding
description: Load and unload a card's stored balance for prepaid-style cards.
- name: Card PIN
description: >-
Set and manage card PINs. `reset-pin` covers physical cards;
`manage-card-pin` covers virtual cards.
- name: Card Add-ons
description: >-
Product-specific card capabilities. Each operation applies only to certain
card products — see [Card
products](/card-issuance/v1.6/guide/card-products).
- name: Card Arts
description: >-
Manage the visual designs (card arts) available to your issuing account.
Set an account-wide default, or pass `card_art_id` when issuing or
updating a card to override per card. Available on Personal Visa.
- name: Cardholders
description: >-
You can create cardholders, which are authorized representatives of your
business that can be issued cards.
- name: Transactions
description: >-
These APIs allow you to retrieve information on transactions that are made
on your user's cards.
- name: Products
description: >-
With this set of APIs, you will be able to create card orders for your
customers.
- name: Balances
description: >-
The available and pending amounts for each currency are broken down
further by payment source types. You can retrieve it to see the balance
currently on your issuing account.
- name: Transfers
description: Transfer funds between issuing accounts.
- name: Reports
description: Generate and download issuing reports.
- name: Simulator
description: Simulate card transactions on the sandbox environment.
paths:
/v1/issuing/cards/manage/pin:
post:
tags:
- Card PIN
summary: Set or Reset Virtual Card PIN
description: >
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](/card-issuance/v1.6/api-reference/reset-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.
operationId: manage-card-pin
parameters:
- $ref: '#/components/parameters/XOnBehalfOf'
- $ref: '#/components/parameters/XIdempotencyKey'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageCardPinRequest'
responses:
'200':
headers:
x-response-id:
$ref: '#/components/headers/XResponseId'
description: PIN operation request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/ManageCardPinResponse'
title: ManageCardPinResponse
security:
- XAuthToken: []
components:
parameters:
XOnBehalfOf:
in: header
name: x-on-behalf-of
schema:
type: string
required: false
description: >
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](/account-center/v1.6/api-reference/list-connected-accounts)
endpoint. If omitted or empty, the request is executed using the master
account.
More information at [Connected
Accounts](/account-center/v1.6/guide/connected-accounts).
example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
XIdempotencyKey:
in: header
name: x-idempotency-key
schema:
type: string
format: uuid
required: true
description: >-
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.
example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
schemas:
ManageCardPinRequest:
type: object
required:
- card_id
- type
- pin
properties:
card_id:
type: string
format: uuid
description: Unique identifier for the card. Must be a Standard virtual card.
example: 630be6bd-2652-4faa-9f3d-2c51cee0b820
type:
type: string
description: >
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`.
enum:
- SET
- RESET
example: SET
pin:
type: string
description: The new PIN for the card. Must be exactly 4 numeric digits.
pattern: ^\d{4}$
minLength: 4
maxLength: 4
example: '1234'
old_pin:
type: string
description: >-
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`.
pattern: ^\d{4}$
minLength: 4
maxLength: 4
example: '5678'
ManageCardPinResponse:
type: object
required:
- card_id
- card_order_id
- create_time
properties:
card_id:
$ref: '#/components/schemas/CardId'
card_order_id:
$ref: '#/components/schemas/CardOrderId'
create_time:
$ref: '#/components/schemas/CreateTime'
CardId:
type: string
example: c0cef051-29c5-4796-b86a-cd5b684bfad7
description: Unique identifier for the card.
CardOrderId:
type: string
example: c0cef051-29c5-4796-b86a-cd5ee34bfad7
description: ID of the card order.
CreateTime:
type: string
description: Create time at which the object was created.
example: '2024-03-21T17:17:32+08:00'
headers:
XResponseId:
description: >-
Universally unique identifier (UUID v4) for the response. Helpful for
identifying a request when communicating with UQPAY support.
schema:
type: string
format: uuid
example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
securitySchemes:
XAuthToken:
type: apiKey
in: header
name: x-auth-token
description: The API token for login provided by UQPay.
````