> ## 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 码，并为实体卡配置免密交易阈值。

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

> [!NOTE]
>
> 支持 PIN 管理的实体卡和虚拟卡均可管理 PIN，具体操作以卡片能力为准。

## 激活时设置 PIN 码

激活实体卡时必须设置 PIN 码。在 [Activate Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/activate-card.md) 请求中加入 `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"
  }'
```

## 重置 PIN 码

使用 [Manage Card PIN](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/reset-pin.md) 接口修改卡片 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"
  }'
```

## 免密支付阈值

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

### 默认行为

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

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

### 支持范围

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

### 支持的 BIN

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

### 配置阈值

更新卡片时设置 `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
  }'
```

## 交易决策逻辑

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

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

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

## 相关文档

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.