Quickstart 与手工联调工具

更新时间: 2026-11-05 02:13

SDK 仓库内置服务端联调示例，用于帮助商户使用已批准凭据确认 SDK 初始化、只读查询、创建请求保护和未知结果查单流程。Demo 不替代商户自己的订单库、密钥管理、 Webhook 验签或生产发布流程。

版本与下载

版本	状态	下载入口	描述
`1.2.1`	已发布（2026-11-04）	Quickstart v1.2.1	与公开接口版本 `1.0`、SDK `1.2.1` 配套；Quickstart 和手工联调工具支持代收付款人邮箱与手机号，以及可选 successUrl。

GitHub Release v1.2.1 · SDK 源码标签 v1.2.1

配套 SDK 源码包含 examples/Quickstart.java、本地 Keys.java，以及五个一一对应最终接口的手工联调类：BalanceQueryLocalTestTool、PaymentCreateLocalTestTool、 PaymentQueryLocalTestTool、PayoutCreateLocalTestTool、PayoutQueryLocalTestTool。五个类统一读取 intl-sdk-local.properties，均可直接从 IDE 运行各自的 main。运行前先完成快速开始中的凭据接入准备，并按 SDK 页面完成下载与安装。

环境变量

v1.2.1 Quickstart 沿用现有只读默认行为和代收示例。巴西 PIX 代付请使用 PayoutCreateLocalTestTool，通过 recipientAccountType 替代 recipientBankCode，详见 SDK 页面。升级 SDK 不会自动开启生产写操作。

text

INTL_API_BASE_URL
INTL_API_KEY
INTL_API_SECRET
INTL_COUNTRY
INTL_CURRENCY

INTL_API_BASE_URL 必须使用已批准的 HTTPS 接口域名，不能包含 /intl/v1 路径前缀。商户先使用测试环境凭据联调，上线审批通过后再使用生产凭据。

只读联调

Demo 默认只执行余额查询，用于验证 Base URL、API Key、API Secret、 Timestamp、Nonce 和 Signature 是否正确。只读联调通过后，再进入创建请求测试。

创建请求测试

创建类请求默认关闭。只有明确设置写操作开关，并提供目标环境对应的金额、产品编码和商户订单号后， Demo 才会发送创建请求。

text

INTL_ENABLE_WRITES=true
INTL_PAYMENT_AMOUNT
INTL_PAYMENT_PRODUCT_CODE
INTL_MERCHANT_ORDER_NO
INTL_PAYMENT_PAYER_EMAIL
INTL_PAYMENT_PAYER_PHONE
INTL_PAYMENT_SUCCESS_URL

INTL_PAYMENT_PAYER_EMAIL 与 INTL_PAYMENT_PAYER_PHONE 均为选填的付款人联系方式。

INTL_PAYMENT_SUCCESS_URL 为可选的商户 HTTPS 域名成功返回地址；未设置或零长度时不发送，非空原文不裁剪或编码，按实际发送内容签名。手工工具使用 paymentSuccessUrl 配置。服务端先验签，再将不可用地址按未传过滤；纯 QRPH 忽略该字段。同号重试保持首次生效地址一致，被过滤值与未传等价；响应不回显该字段。商户不得依据浏览器返回确认收款。详见 SDK。

创建请求发出前必须先记录 merchantOrderNo。HTTP 200 表示接口调用成功，业务结果以响应体 status、查单接口或 Webhook 为准。HTTP 5xx、超时、断连或无法验证的响应，可能无法确认订单是否已经创建，必须先按原 merchantOrderNo 查单。连续查询一段时间仍查不到订单时，只能用同一原单号和完全一致的请求重发，不要另建订单。

使用边界

Demo 只能在商户服务端或受控开发机运行，不能放到浏览器或移动端。
API Secret 和 Webhook Secret 只能来自服务端环境变量或密钥管理系统。
Demo 不自动重试创建请求。
必须确认调用出口 IP 已由平台运营加入网关安全组白名单。
上线审批通过后才能开启生产写操作，所有示例值必须替换为获批的生产测试数据。

Quickstart 与手工联调工具 ​

版本与下载 ​

环境变量 ​

只读联调 ​

创建请求测试 ​

使用边界 ​