Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Card PIN

Set or Reset Virtual Card 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 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/v1/issuing/cards/manage/pin

Headers

x-on-behalf-ofstring

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 API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-keystring uuid

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.

Request body

card_idstring 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.
pinstring required

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

old_pinstring

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.

Example request

{
  "card_id": "630be6bd-2652-4faa-9f3d-2c51cee0b820",
  "type": "SET",
  "pin": "1234",
  "old_pin": "5678"
}

Response

PIN operation request accepted.

card_idstring required

Unique identifier for the card.

card_order_idstring required

ID of the card order.

create_timestring date/time required

The timestamp when the record was created in the system. Timestamp follows the ISO 8601 standard.

Example response

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "create_time": "2024-03-01T00:00:00+08:00"
}