> ## Documentation Index > Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 管理卡片 PIN > 设置、重置或修改卡片 PIN。 ## OpenAPI ````yaml /zh/card-issuance/v1.6/issuing.yaml post /v1/issuing/cards/pin openapi: 3.0.2 info: title: Issuing API version: 0.0.1 x-source-en-commit: 6841624 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/pin: post: tags: - Card PIN summary: 管理卡片 PIN description: 设置、重置或修改卡片 PIN。 operationId: reset-pin parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetPINRequest' responses: '200': headers: x-response-id: $ref: '#/components/headers/XResponseId' description: PIN 操作订单已受理，不代表 PIN 已变更。 content: application/json: examples: sandbox: summary: Sandbox response value: request_status: SUCCESS card_id: eeeed4ff-e5b6-4e10-b3ae-156996192174 card_order_id: d8102e17-e21a-4574-878f-6824fa5abb6b order_status: PROCESSING create_time: '2026-09-10T16:14:49.721921515+08:00' schema: $ref: '#/components/schemas/SetPINResponse' title: SetPINResponse 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: SetPINRequest: type: object required: - card_id - pin properties: card_id: type: string format: uuid description: 需要管理的卡片，必须已激活且未过期。同一卡片已有 PIN 操作正在处理时，请等待该操作完成后再提交。 type: type: string enum: - SET - RESET - UPDATE default: SET description: >- 不传时默认为 `SET`，按首次设置 PIN 处理。首次设置使用 `SET`；无需旧 PIN 重置时，必须显式传入 `RESET`；验证旧 PIN 后修改使用 `UPDATE`。支持的操作以卡片能力为准，不支持时返回 `pin_operation_not_supported`。 pin: type: string pattern: ^[0-9]{6}$ description: 新 PIN。不能全部为同一数字、不能出现在持卡人手机号的连续数字中，后四位不能与卡号后四位相同。修改时必须与旧 PIN 不同。 oneOf: - title: Set PIN properties: type: enum: - SET not: required: - old_pin - title: Reset PIN required: - type properties: type: enum: - RESET default: RESET not: required: - old_pin - title: Update PIN properties: type: enum: - UPDATE default: UPDATE old_pin: type: string pattern: ^[0-9]{6}$ description: >- 当前 PIN，验证通过后才执行修改。仅 `UPDATE` 必填，`SET` 和 `RESET` 禁止传入。当前 PIN 必须为六位数字。 required: - type - old_pin SetPINResponse: type: object required: - request_status - card_id - card_order_id - order_status - create_time properties: request_status: type: string enum: - SUCCESS description: 请求已受理，不是 PIN 操作的最终结果。 card_id: type: string format: uuid description: 订单关联的卡片。 card_order_id: type: string format: uuid description: >- 用于跟踪 PIN 操作的订单 ID。通过[查询卡订单](/zh/card-issuance/v1.6/api-reference/retrieve-card-order)或卡订单 Webhook 获取最终结果。 order_status: type: string enum: - PROCESSING description: > PIN 操作订单状态： - `PROCESSING`：已受理，正在处理，尚未确认 PIN 变更完成。 - `SUCCESS`：处理完成，PIN 已变更。 - `FAILED`：操作失败。 本接口受理响应固定返回 `PROCESSING`。通过订单查询或卡订单 Webhook 获取最终状态。 接口订单状态使用大写；卡更新 Webhook 使用小写：`pending` 表示处理中，`success` 表示成功，`failed` 表示失败。 create_time: type: string format: date-time description: 订单创建时间，采用 RFC3339 格式。 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。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.