跳转到主要内容
POST
管理卡片 PIN

授权

x-auth-token
string
header
必填

由 UQPAY 提供的登录 API Token。

请求头

x-on-behalf-of
string

指定代表哪个子账户发起请求。应设置为 account_id,该值可通过 List Connected Accounts 接口获取。若省略或为空,则请求以主账户身份执行。 更多信息参见 关联账户。

x-idempotency-key
string<uuid>
必填

用于维持操作幂等性的唯一标识符(UUID),确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败的情况下保持数据一致性。

请求体

application/json
card_id
string<uuid>
必填

需要管理的卡片,必须已激活且未过期。同一卡片已有 PIN 操作正在处理时,请等待该操作完成后再提交。

pin
string
必填

新 PIN。不能全部为同一数字、不能出现在持卡人手机号的连续数字中,后四位不能与卡号后四位相同。修改时必须与旧 PIN 不同。

Pattern: ^[0-9]{6}$
type
enum<string>
默认值:SET

不传时默认为 SET,按首次设置 PIN 处理。首次设置使用 SET;无需旧 PIN 重置时,必须显式传入 RESET;验证旧 PIN 后修改使用 UPDATE。支持的操作以卡片能力为准,不支持时返回 pin_operation_not_supported。

可用选项:
SET

响应

200 - application/json

PIN 操作订单已受理,不代表 PIN 已变更。

request_status
enum<string>
必填

请求已受理,不是 PIN 操作的最终结果。

可用选项:
SUCCESS
card_id
string<uuid>
必填

订单关联的卡片。

card_order_id
string<uuid>
必填

用于跟踪 PIN 操作的订单 ID。通过查询卡订单或卡订单 Webhook 获取最终结果。

order_status
enum<string>
必填

PIN 操作订单状态:

  • PROCESSING:已受理,正在处理,尚未确认 PIN 变更完成。
  • SUCCESS:处理完成,PIN 已变更。
  • FAILED:操作失败。

本接口受理响应固定返回 PROCESSING。通过订单查询或卡订单 Webhook 获取最终状态。 接口订单状态使用大写;卡更新 Webhook 使用小写:pending 表示处理中,success 表示成功,failed 表示失败。

可用选项:
PROCESSING
create_time
string<date-time>
必填

订单创建时间,采用 RFC3339 格式。