> ## 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. # 静态二维码 > 创建可重复使用的收款二维码、获取二维码内容，并通过收单 Webhook 对账。 静态二维码用于在门店或收银台展示可重复使用的付款码。你可以设置固定金额，也可以让付款人输入金额。每笔付款分别通过 PaymentIntent 和 PaymentAttempt 资源跟踪。 ## 开始前 准备 API 凭证和有效的[访问 Token](https://developers.uqpay.com/zh/account-center/v1.6/api-reference/access-token.md)。每次请求都携带 `x-client-id` 和 `x-auth-token`。 如果你管理已关联的子账户，通过 `x-on-behalf-of` 选择有权操作的子账户。创建、查询、列表查询和更新码时，使用相同的目标账户。省略此请求头时，使用凭证关联的账户。 ## 查询可用选项 针对目标账户调用 [Get static QR options](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/get-static-qr-options.md)。结合 `eligible` 和 `ineligible_reasons` 检查账户及所选支付方式的配置要求。`payment_methods` 中列出某个方式不代表其渠道配置已齐全；某一方式缺少配置，也不一定阻止其他方式创建。具体创建请求是否被接受，以创建响应为准。需要配置协助时联系 UQPAY 支持团队。 从返回的 `payment_methods` 和 `currencies` 中选择支付方式和币种。可用选项取决于目标账户；其他账户支持某种支付方式，不代表你的账户也可使用。 ## 创建二维码 调用 [Create a static QR code](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/create-static-qr-code.md)，传入选择的支付方式、币种和金额模式。每次新建使用新的 `x-idempotency-key`；响应不明确时，以相同键重试相同请求。同一键用于不同参数会返回 HTTP 409。 | 金额模式 | 金额输入方式 | | - | - | | `FIXED` | 创建时提供以主货币单位表示、恰好保留两位小数的正数 `amount` 字符串。 | | `DYNAMIC` | 由付款人输入金额。创建请求中完全省略 `amount`。 | `DYNAMIC` 表示静态码的金额模式，并不意味着每笔付款都要生成新的二维码。此模式下，不要将 `amount` 设为 `null`、空字符串或 `"0.00"`。 你可以指定门店名称和自定义 `code_no`。省略或传空字符串时，门店名称默认使用目标账户名称，码牌号由系统生成。自定义新码牌号最多 10 位，仅含 ASCII 字母和数字；`options` 和 `requests` 为保留值。将 `code_no` 作为区分大小写的字符串处理，并保留前导零。门店名称最多 25 字节。可选文本字段不接受 `null`。 `extension` 用于保存自己的关联信息，不会编码到二维码支付参数中。 ## 查询并展示二维码 保存返回的 `code_no`。创建响应中的 `status: INITIATED` 表示已开始创建，不代表二维码已可展示，也不代表客户已经付款。 通过 [Retrieve a static QR code](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/retrieve-static-qr-code.md) 查询资源，通过 [Retrieve static QR code details](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/retrieve-static-qr-code-details.md) 获取 `qr_payload`。创建仍为 `INITIATED` 时，详情可能返回 404；等待后重试，不要因此重复创建。为查询设置重试次数上限，持续未就绪时联系 UQPAY 支持团队。仅在创建成功且内容可用后展示二维码。使用二维码渲染库对返回的内容原样编码。 静态码的 `SUCCEEDED` 状态描述码的创建结果。判断某笔付款是否成功，应使用支付通知。 ## 接收付款通知与对账 配置 [PaymentIntent Result](https://developers.uqpay.com/zh/global-acquiring/v1.6/webhooks/paymentintent-result.md) 和 [PaymentAttempt Result](https://developers.uqpay.com/zh/global-acquiring/v1.6/webhooks/paymentattempt-result.md) 通知。静态码支付使用这些收单事件。 以 `data.account_id` 确认交易所属账户，再用码牌号关联静态码，最后用 `data.payment_intent_id` 和 `data.payment_attempt_id`（PaymentAttempt 通知）分别跟踪每笔付款。码牌号可以重复用于多笔付款，不能代替单笔付款标识符。 下表的 `` 表示 `data.payment_method.type` 指定的支付方式详情对象，例如 `paynow`。静态码关联字段仅在交易包含对应信息时返回。 | 静态码字段或配置 | Webhook 字段 | 对账含义 | | - | - | - | | `extension` | `data.payment_method..static_qrcode_extension` | 关联你自己的门店或业务信息；不是 `data.metadata` 或商户订单号。 | | `code_no` | `data.payment_method..static_qrcode_number_plate` | 本次付款关联的码牌号；保留大小写和前导零。 | | 详情响应 `qr_payload` | `data.payment_method..static_qrcode` | 本次付款关联的静态二维码内容。 | | `payment_methods` | `data.payment_method.type` 及对应详情对象 | 通知表示本次交易实际使用的单一支付方式，不回传创建时的数组。 | | `currency`、`amount` | `data.currency`、`data.amount` | 使用单笔交易的币种与金额对账；DYNAMIC 静态码的 `amount: null` 不是交易金额。 | | 目标账户 | `data.account_id` | 交易所属账户；结合码牌号定位业务归属。 | 金额模式、门店名称、城市、码的创建状态和创建时间属于静态码资源信息，不要将其视为付款通知中的同名字段。付款通知的时间与状态描述的是交易。 通知结构见 [PaymentIntent Result](https://developers.uqpay.com/zh/global-acquiring/v1.6/webhooks/paymentintent-result.md) 中的静态码支付样例。单个 PaymentAttempt 失败，不代表对应 PaymentIntent 已失败。 ## 查找二维码与更新关联信息 通过 [List static QR codes](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/list-static-qr-codes.md) 查询目标账户内的二维码。可按码牌号、币种、支付方式和创建时间筛选。按 `code_no` 筛选时保留前导零。列表在 `data` 返回条目，`total_items` 表示匹配的码总数，`total_pages` 表示总页数。当前 `page_number` 小于 `total_pages` 时，可请求下一页。 时间筛选须同时提供 `create_start_time` 和 `create_end_time`，使用 `YYYY-MM-DDTHH:mm:ss+08:00` 格式。开始须早于结束，跨度最多 30 天。查询字符串中的加号需编码为 `%2B`。 通过 [Update static QR code extension](https://developers.uqpay.com/zh/global-acquiring/v1.6/api-reference/update-static-qr-code-extension.md) 修改 `extension`。最多 512 个字符，空字符串可清空，不接受 `null`。更新不要求幂等键，也不会按幂等键回放旧响应。该操作更新关联信息，不修改二维码的支付方式、币种、金额模式或金额。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.