---
title: "Set or Reset Virtual Card PIN"
method: POST
path: "/v1/issuing/cards/manage/pin"
tags: ["Card PIN"]
---

# Set or Reset Virtual Card PIN

`POST /v1/issuing/cards/manage/pin`

<a href="/card-issuance/v1.6/guide/card-products" style={{display:'inline-block',padding:'2px 10px',borderRadius:'9999px',fontSize:'12px',fontWeight:600,lineHeight:'18px',background:'#EEF2FF',color:'#4338CA',border:'1px solid #C7D2FE',textDecoration:'none'}}>Business Mastercard only</a>

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.

## Headers

- `x-on-behalf-of` string
- `x-idempotency-key` string, uuid

## Request body

- ManageCardPinRequest
  - `card_id` string, uuid, required — Unique identifier for the card. Must be a Standard virtual card.
  - `type` 'SET' | 'RESET', 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`.
  - `pin` string, required — The new PIN for the card. Must be exactly 4 numeric digits.
  - `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`.

## Response `200`

PIN operation request accepted.

- ManageCardPinResponse
  - `card_id` string, required — Unique identifier for the card.
  - `card_order_id` string, required — ID of the card order.
  - `create_time` string, date/time, required — The timestamp when the record was created in the system. Timestamp follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.

---

[API](https://skmtc.dev/uqpay/apis/authentication-api.md) · [All operations](https://skmtc.dev/uqpay/apis/authentication-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uqpay/authentication-api/revisions/cef532a10777/schema)