> ## 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
在 **Standard 虚拟卡** 上设置或重置 PIN 码。
- `type: SET` —— 首次设置 PIN 码。若卡片已有 PIN 码则失败，此时请改用 `RESET`。
- `type: RESET` —— 修改 PIN 码。请求必须携带 `old_pin`，且需与卡片当前的 PIN 码一致。
> **无忘记 PIN 流程。** `RESET` 始终要求通过 `old_pin` 提供当前 PIN 码。若当前 PIN 码遗失，则无法通过本接口重置——请联系 UQPAY 协助。
**仅适用于 Standard 虚拟卡。** 此接口不适用于实体卡——实体卡 PIN 码请使用 [重置卡片 PIN 码](/zh/card-issuance/v1.6/api-reference/reset-pin) 管理。
**异步处理**
同步响应仅确认请求已受理，并返回 PIN 操作订单（`card_id`、`card_order_id`、`create_time`）。使用相同 `x-idempotency-key` 的重复请求返回相同结果，不会重复处理。一张卡片同一时间只能有一笔进行中的 PIN 操作——在一笔操作仍在处理时再提交 `SET` / `RESET` 请求会被拒绝。
## OpenAPI
````yaml /zh/card-issuance/v1.6/issuing.yaml post /v1/issuing/cards/manage/pin
openapi: 3.0.2
info:
title: Issuing API
version: 0.0.1
x-source-en-commit: fdf4a2b
x-source-en-path: card-issuance/v1.6/issuing.yaml
description: >
UQPAY Issuing API 让你签发虚拟卡、管理持卡人，并监控卡交易。
## 功能概览
- 创建并管理虚拟卡（签发、激活、冻结、注销）
- 通过 KYC 完成持卡人入驻与验证
- 设置消费限额与卡控制
- 为卡余额充值与提现
- 查询卡交易与账户余额
- 在发卡账户之间转账
- 生成并下载报表
## 身份认证
所有请求都需要携带有效的鉴权 Token，Token 通过 [Access
Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在
`x-auth-token` 请求头中携带该 Token。
## 幂等性
POST 请求支持 `x-idempotency-key` 请求头，可安全重试而不会创建重复资源。
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: 沙盒环境基础 URL。
- url: https://api.uqpay.com/api
description: 生产环境基础 URL。
security: []
tags:
- name: Card Lifecycle
description: 创建卡片并管理其完整生命周期——签发、查询、更新、激活、绑定与变更状态。
- name: Card Secure Data
description: 通过 PCI 合规接口或令牌化 iframe 访问敏感卡数据（PAN、CVV）。是否可用取决于你的 PCI 状态，而非卡产品。
- name: Card Funding
description: 为预付类卡片充值或提取其卡内储值余额。
- name: Card PIN
description: 设置并管理卡片 PIN 码。`reset-pin` 用于实体卡，`manage-card-pin` 用于虚拟卡。
- name: Card Add-ons
description: >-
产品专属的卡功能。每个操作仅适用于特定卡产品——参见
[卡产品](/zh/card-issuance/v1.6/guide/card-products)。
- name: Card Arts
description: >-
管理发卡账户可用的视觉设计（卡面）。可设置账户级默认卡面，或在签发/更新卡片时传入 `card_art_id` 以按卡覆盖。仅 Personal
Visa 支持。
- name: Cardholders
description: 你可以创建持卡人。持卡人是你企业的授权代表，可被签发卡片。
- name: Transactions
description: 这些接口用于查询在你用户卡片上发生的交易信息。
- name: Products
description: 通过这组接口，你可以为客户创建卡订单。
- name: Balances
description: 各币种的可用金额与待处理金额会进一步按资金来源类型细分。你可以查询它，查看发卡账户当前的余额。
- name: Transfers
description: 在发卡账户之间转账。
- name: Reports
description: 生成并下载发卡报表。
- name: Simulator
description: 在沙盒环境中模拟卡交易。
paths:
/v1/issuing/cards/manage/pin:
post:
tags:
- Card PIN
summary: Set or Reset Virtual Card PIN
description: >
仅 Business Mastercard
在 **Standard 虚拟卡** 上设置或重置 PIN 码。
- `type: SET` —— 首次设置 PIN 码。若卡片已有 PIN 码则失败，此时请改用 `RESET`。
- `type: RESET` —— 修改 PIN 码。请求必须携带 `old_pin`，且需与卡片当前的 PIN 码一致。
> **无忘记 PIN 流程。** `RESET` 始终要求通过 `old_pin` 提供当前 PIN 码。若当前 PIN
码遗失，则无法通过本接口重置——请联系 UQPAY 协助。
**仅适用于 Standard 虚拟卡。** 此接口不适用于实体卡——实体卡 PIN 码请使用 [重置卡片 PIN
码](/zh/card-issuance/v1.6/api-reference/reset-pin) 管理。
**异步处理**
同步响应仅确认请求已受理，并返回 PIN 操作订单（`card_id`、`card_order_id`、`create_time`）。使用相同
`x-idempotency-key` 的重复请求返回相同结果，不会重复处理。一张卡片同一时间只能有一笔进行中的 PIN
操作——在一笔操作仍在处理时再提交 `SET` / `RESET` 请求会被拒绝。
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 操作请求已受理。
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: >
指定代表哪个子账户发起请求。应设置为 `account_id`，该值可通过 [List Connected
Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts)
接口获取。若省略或为空，则请求以主账户身份执行。
更多信息参见 [关联账户](/zh/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: 用于维持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败的情况下保持数据一致性。
example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
schemas:
ManageCardPinRequest:
type: object
required:
- card_id
- type
- pin
properties:
card_id:
type: string
format: uuid
description: 卡片的唯一标识符。必须是 Standard 虚拟卡。
example: 630be6bd-2652-4faa-9f3d-2c51cee0b820
type:
type: string
description: |
要执行的 PIN 操作。
* `SET` - 首次设置卡片 PIN 码。若卡片已有 PIN 码则被拒绝。
* `RESET` - 修改卡片 PIN 码。需要 `old_pin`。
enum:
- SET
- RESET
example: SET
pin:
type: string
description: 卡片的新 PIN 码。必须恰好为 4 位数字。
pattern: ^\d{4}$
minLength: 4
maxLength: 4
example: '1234'
old_pin:
type: string
description: >-
卡片当前的 PIN 码。当 `type` 为 `RESET` 时必填，且必须与卡片当前设置的 PIN 码一致，否则操作失败。当
`type` 为 `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: 卡片的唯一标识符。
CardOrderId:
type: string
example: c0cef051-29c5-4796-b86a-cd5ee34bfad7
description: 卡订单的 ID。
CreateTime:
type: string
description: 对象的创建时间。
example: '2024-03-21T17:17:32+08:00'
headers:
XResponseId:
description: 响应的全局唯一标识符（UUID v4）。在联系 UQPAY 支持团队时有助于定位某次请求。
schema:
type: string
format: uuid
example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
securitySchemes:
XAuthToken:
type: apiKey
in: header
name: x-auth-token
description: 由 UQPay 提供的登录 API Token。
````