> ## 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.

# PIN 与免密支付

> 管理卡片 PIN 码，并为实体卡配置免密交易阈值。

实体卡需要 PIN 码进行交易身份验证。UQPAY 还支持配置免密阈值，让持卡人无需输入 PIN 码即可完成小额购物。

<Note>
  PIN 码设置仅适用于实体卡。虚拟卡不使用 PIN 码。
</Note>

<h2 id="set-pin-at-activation">激活时设置 PIN 码</h2>

激活实体卡时必须设置 PIN 码。在 [Activate Card](/zh/card-issuance/v1.6/api-reference/activate-card) 请求中加入 `pin` 字段：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/activate \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "activation_code": "81534005",
    "pin": "123456"
  }'
```

<h2 id="reset-pin">重置 PIN 码</h2>

使用 [Reset Card PIN](/zh/card-issuance/v1.6/api-reference/reset-pin) 接口修改卡片 PIN 码：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/pin \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "pin": "567890"
  }'
```

<h2 id="no-pin-payment-threshold">免密支付阈值</h2>

`no_pin_payment_amount` 参数设置一个交易金额阈值，低于该金额的交易无需输入 PIN 码。这能优化小额、高频消费（尤其是非接触式支付）的结账体验。

<h3 id="default-behavior">默认行为</h3>

| 条件                             | 行为                    |
| ------------------------------ | --------------------- |
| 未设置 `no_pin_payment_amount`    | 不超过 **200 SGD** 的交易免密 |
| `no_pin_payment_amount` 设为 `0` | 所有交易都需要 PIN 码         |
| `no_pin_payment_amount` 设为某个值  | 不超过该金额的交易免密           |

以 USD 签发的卡片，默认阈值对应 200 SGD 按当前汇率换算后的 USD 等值金额。

<h3 id="supported-ranges">支持范围</h3>

| 币种  | 范围        |
| --- | --------- |
| USD | 0 – 2,000 |
| SGD | 0 – 2,600 |

<h3 id="supported-bins">支持的 BIN</h3>

| 环境 | BIN                                         |
| -- | ------------------------------------------- |
| 生产 | `49372410`、`49372408`、`49372434`、`45659910` |
| 沙盒 | `40963608`                                  |

<h3 id="configure-the-threshold">配置阈值</h3>

更新卡片时设置 `no_pin_payment_amount`：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "no_pin_payment_amount": 500
  }'
```

<h2 id="transaction-decision-logic">交易决策逻辑</h2>

授权结果取决于三个因素：卡片是否设置了 PIN 码、是否配置了自定义免密限额、以及交易金额。

| 是否有 PIN |    是否配置免密限额   | 交易金额      | 结果                              |
| :-----: | :-----------: | :-------- | :------------------------------ |
|    是    |       否       | ≤ 200 SGD | 免密通过（或输入正确 PIN 码通过）。PIN 码错误则拒绝。 |
|    是    |       否       | > 200 SGD | 需要 PIN 码。未输入或输入错误则拒绝。           |
|    是    | 是（例如 500 SGD） | ≤ 自定义限额   | 免密通过（或输入正确 PIN 码通过）。PIN 码错误则拒绝。 |
|    是    | 是（例如 500 SGD） | > 自定义限额   | 需要 PIN 码。未输入或输入错误则拒绝。           |

<Warning>
  如果卡片未设置 PIN 码，也未配置免密限额，大额交易会因缺少身份验证凭证而失败。激活卡片时务必设置 PIN 码。
</Warning>

<h2 id="related">相关文档</h2>

* [Activate Card API](/zh/card-issuance/v1.6/api-reference/activate-card)
* [Update Card API](/zh/card-issuance/v1.6/api-reference/update-card)
* [Reset Card PIN API](/zh/card-issuance/v1.6/api-reference/reset-pin)
* [签发实体卡](/zh/card-issuance/v1.6/guide/issue-physical-cards)