> ## Documentation Index
> Fetch the complete documentation index at: https://docs-payment-merchant.keysecure.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置实体卡 PIN 码

设置实体卡 PIN 码。仅支持**实体卡**（Physical），卡状态须为正常（`Activated`）。`pin` 须使用 **AES/ECB/PKCS5Padding + Base64** 加密后传入。

<Note>
  * 仅支持实体卡，虚拟卡调用返回 **4017**
  * 明文 PIN 须为 **6 位纯数字**，且不可含三位及以上相同或连续数字（如 `111111`、`123456`），否则返回 **4016**
  * 卡状态须为 `Activated`，否则返回 **4005**
  * 加密算法详见「代码工具类」章节
</Note>

## 请求头

<ParamField header="Api-Key" type="string" required placeholder="your_api_key">
  apiKey（商户凭证，与 IP 白名单绑定）
</ParamField>

<ParamField header="Timestamp" type="string" required>
  Unix 时间戳（毫秒），与服务端偏差须在 60 秒内，且不接受未来时间戳
</ParamField>

<ParamField header="Access-Token" type="string" required placeholder="your_access_token">
  登录标识（除获取 Token 外必填）
</ParamField>

<ParamField header="Content-Type" type="string" default="application/json">
  固定为 `application/json`
</ParamField>

## 请求体

<ParamField body="card_no" type="string" required>
  卡单号
</ParamField>

<ParamField body="cardholder_no" type="string" required>
  持卡人单号
</ParamField>

<ParamField body="pin" type="string" required placeholder="Base64EncodedEncryptedPin...">
  加密后的 PIN（Base64 密文）
</ParamField>

## 返回参数

<ResponseField name="code" type="number">
  响应状态码，`0` 表示成功
</ResponseField>

<ResponseField name="msg" type="string">
  响应消息
</ResponseField>

<ResponseField name="data" type="object">
  返回数据

  <Expandable title="data">
    <ResponseField name="result" type="boolean">设置结果</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url https://sandbox-openplatform.keysecure.io/open-api/v1/card/pin/set \
    --header 'Content-Type: application/json' \
    --header 'Api-Key: your_api_key' \
    --header 'Timestamp: 1716307200000' \
    --header 'Access-Token: your_access_token' \
    --data '{
      "card_no": "C202605220001",
      "cardholder_no": "U202605220001",
      "pin": "Base64EncodedEncryptedPin..."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 0,
    "msg": "Success",
    "data": {"result": true}
  }
  ```
</ResponseExample>