快速开始

更新时间: 2026-09-08 14:00

接入主线

按下面顺序完成接入：

获得国际业务准入后，在商户 Portal 创建 API 凭据并安全保存 API Secret。
独立创建一个或多个 Webhook Endpoint 并选择订阅事件。
生成请求签名。
创建收款或代付订单。
按商户订单号查单。
处理通知事件。
安全处理创建结果。
完成上线检查后切换生产凭据。

1. 在商户 Portal 创建 API 凭据

商户管理员或明确授权的技术人员在“国际支付接入 → API 接入”中填写凭据名称。平台生成 API Key 和 API Secret，新 Key 固定为停用状态。创建成功后，API Secret 只在当前页面会话中展示一次；确认妥善保存前可在该页面继续复制，刷新或关闭浏览器后无法再次查看或找回。必须立即保存到服务端密钥管理系统，不能写入前端、移动端、仓库、日志或工单。如果 Secret 未保存或可能泄露，应创建替代 Key 完成轮换。

先使用测试环境凭据完成联调。未完成准入、产品、账户、渠道及资金故障测试，且生产出口 IP 未由平台运营加入网关安全组白名单前，不得启用生产凭据或发送生产交易。

API Base URL

API Reference 中的接口地址按 {apiBaseUrl} 加带版本前缀的接口 Path 展示，例如 POST {apiBaseUrl}/intl/v1/payment/order/create。调用时不能按字面值发送 {apiBaseUrl}，应替换为对应环境的 HTTPS 接口域名：

环境	`{apiBaseUrl}`
测试环境	`https://test-api.paysea.global`
生产环境	`https://api.paysea.global`

例如创建收款订单：

测试环境：POST https://test-api.paysea.global/intl/v1/payment/order/create
生产环境：POST https://api.paysea.global/intl/v1/payment/order/create

商户应先使用测试环境完成联调；生产上线时再替换为生产环境 {apiBaseUrl}、生产商户编号、API Key 和 API Secret。

这里的测试环境指平台下发的联调域名和凭据，不等同于 API Key 的 test 模式。当前公开接口使用 live 模式 Key；test 模式仅为未来隔离 Sandbox 预留。

示例统一读取：

text

INTL_API_BASE_URL
INTL_MERCHANT_NO
INTL_API_KEY
INTL_API_SECRET

示例中的 INTL_API_BASE_URL 用于保存 {apiBaseUrl} 对应的 HTTPS 接口域名，不能包含 /intl/v1 路径前缀。INTL_MERCHANT_NO 用于对账、排障和确认幂等归属，不作为额外请求头发送；API Key 已绑定对应商户编号。

2. 配置 Webhook Endpoint 和独立 Secret

Webhook 与 API 凭据完全独立：Endpoint 可以在 API Key 之前或之后创建，API Key 的启用、停用或废弃不改变 Webhook 投递。每个 Endpoint 包含一个 HTTPS URL、一个当前 Webhook Secret 和一个或多个订阅事件。同一商户可创建多个 Endpoint，同一事件也可同时投递到多个 Endpoint。

新 Endpoint 默认停用。创建成功后，Webhook Secret 和 Webhook Secret ID 明文展示 60 秒；保存两者、部署具备可靠接收与原始 Body 验签能力的接收端后，再单独启用该 Endpoint。具备 Webhook Secret 查看权限的商户管理员每次重新通过 Google 验证后，可再次查看当前 Secret。修改 URL 会停用 Endpoint 并将待投递记录标记为 SKIPPED，确认新接收端就绪后再启用。API 创建请求既不要求必须存在启用的 Webhook，也不接受每笔订单的通知地址。

不同事件需要发到不同接收端时，分别创建 Endpoint 并勾选各自事件；同一事件需要同时发给多个接收端时，在每个目标 Endpoint 上订阅该事件。

通知接收端必须具备：

使用原始 Body 验签；
按通知 Body eventId 或商户订单号做本地幂等；
对重复通知返回一致处理结果；
验签失败时拒绝处理业务状态。

3. 确认支持产品

只使用平台为当前商户开通的国家、币种、产品和银行编码。公开文档列出当前产品目录， API Reference 列出 PH/PHP 代付 recipient 字段可用的银行编码。不要自行拼接产品码、渠道号或未开通产品。

4. 生成请求签名

每个请求都必须从商户后端发起，并携带独立签名请求头：

http

Accept: application/json
Content-Type: application/json
Api-Key: ik_live_xxx
Timestamp: 1780272000
Nonce: nonce_xxx
Signature: v1=<64位小写十六进制>

Api-Key 用于识别商户、密钥和权限；调用来源由平台运营侧安全组控制。Timestamp 是 Unix 秒级时间戳文本，与 Nonce 一起用于防重放；Signature 用于证明调用方持有 API Secret，并保护请求方法、请求地址和请求体。 API Secret 只用于商户服务端本地计算签名，绝不随请求发送。 Accept 和 Content-Type 用于声明 JSON 报文格式，不参与签名原文；GET 请求不发送 Content-Type。Header 名称大小写不敏感；文档统一展示无品牌前缀的规范 Header 名，调用时不要自行添加产品、公司或品牌前缀。

签名原文固定为五行，每一行后都必须追加一个换行字节 \n，包括最后一行：

text

requestMethod
requestUrl
timestamp
nonce
requestBody

requestMethod 使用大写 HTTP 请求方法，例如 POST 或 GET； requestUrl 是不含域名的请求地址，包含 Path 和原始 Query； requestBody 是最终实际发送的 UTF-8 原始 Body，GET 请求没有 Body 时第五行为空，但仍然保留最后的换行字节。商户自研签名逻辑必须先通过平台提供的签名测试向量。

5. 创建收款或代付订单

创建请求发出前，商户系统必须先生成并保存 merchantOrderNo。它是商户侧唯一订单号，必须在同一个商户编号下唯一。平台按“商户编号 + 商户订单号”识别同一笔业务订单。

json

{
  "amount": {
    "value": "100.50"
  },
  "productCode": "PH_PHP_PAYMENT_QRPH_GCASH",
  "merchantOrderNo": "DEMO_PAY_202606010001",
  "orderDescription": "Virtual order"
}

PH_PHP_PAYMENT_QRPH_GCASH 仅为示例产品编码，不代表当前已开放；只有平台为当前商户开通该产品后，才能在创建请求中使用。所选 productCode 决定交易币种和允许的小数精度；创建请求不要再传 amount.currency。

保存响应 platOrderNo 和 merchantOrderNo。创建接口 HTTP 200 中的 platOrderNo 是核心交易系统真实平台订单号，应作为不透明值使用。HTTP 4xx / 5xx 只返回 error，不包含 platOrderNo。

6. 按商户订单号查单

接口返回 200 表示接口调用成功。对创建类请求，它表示核心订单已存在或命中已有幂等订单，不代表收款或代付已成功。商户系统必须保存 merchantOrderNo，并能按商户订单号查询订单状态。查单结果和通知事件都可能到达，业务系统要以自己的订单库做最终幂等处理。

7. 处理通知事件

通知是平台主动发给商户的订单最终状态事件。处理顺序必须是：

读取并保存原始 UTF-8 Body。
根据 Webhook-Secret-Id 选择本地保存的 Webhook Secret。
使用原始 Body、Timestamp、Nonce 和 Signature 验签。
验签通过后解析 JSON。
按通知 Body eventId 或商户订单号去重。
保存处理结果后返回 HTTP 200 OK。平台会将任意 2xx 响应视为接收成功。

通知可能重复投递，商户不能因为收到重复通知而重复更新资金或发货状态。

8. 安全处理创建结果

所有创建结果都必须在不改变已保存订单标识的前提下处理：

创建结果	商户应处理
HTTP `200`	接口调用成功，业务结果以响应体 `status`、查单接口或 Webhook 为准。
HTTP `4xx`	按 `error.code` 处理，不要盲目重试；修正参数、签名、权限或按限流策略等待后再重新提交。
HTTP `5xx`、网络异常或响应超时	可能无法确认订单是否已经创建，不要换单号重新下单；先按原 `merchantOrderNo` 查单。

如果创建结果还没确认，不要改商户订单号、金额或产品重新下单。连续查询一段时间仍查不到订单时，只能用原 merchantOrderNo 重发完全一致的创建请求；不要并发重发或换单号。代付请求尤其不能因为超时直接重发。

9. 申请生产出口 IP 网络准入

将调用国际版 API 的固定出口 IP 提交给平台运营，由运营加入网关安全组白名单后再开放流量。应用凭据不保存来源 IP 字段，应用层也不执行按凭据的 IP 准入。出口 IP 变化应先完成安全组、WAF 或 API Gateway 变更和连通性验证，再切换生产流量。

10. 启用 `live` 模式 Key 并完成上线检查

完成准入和接入验证后，在 Portal 启用 live 模式 API Key。API 凭据与 Webhook Endpoint 各自维护独立生命周期；Webhook 不可用不会改变 API 认证状态。

生产首笔请求前再次确认：

生产国家、币种、产品和限额已开通；
生产出口 IP 已由平台运营加入网关安全组白名单；
生产 Webhook HTTPS 地址和 Secret 已配置；
merchantOrderNo 生成规则在生产商户编号下唯一；
创建类请求没有自动或并发重试逻辑；确实需要重试时，必须先按原商户订单号查询一段时间，确认仍不存在后再串行重发完全一致的原请求。

报障信息清单

向技术支持报障时只提供：

接口环境：测试环境或生产环境 Base URL；
API Key 模式：当前公开接口固定为 live（test 是未来隔离 Sandbox 预留模式）；
UTC 时间；
商户编号；
商户订单号；
HTTP 状态；
Request-Id 响应 Header；
响应 Body error.code。

禁止发送 API Secret、Webhook Secret、签名请求头值、完整请求 Body、完整通知 Body 或收款人完整账号。

生产流量开始前，请完成上线检查清单。

继续阅读如何签名与验签以及幂等规则。

快速开始 ​

接入主线 ​

1. 在商户 Portal 创建 API 凭据 ​

API Base URL ​

2. 配置 Webhook Endpoint 和独立 Secret ​

3. 确认支持产品 ​

4. 生成请求签名 ​

5. 创建收款或代付订单 ​

6. 按商户订单号查单 ​

7. 处理通知事件 ​

8. 安全处理创建结果 ​

9. 申请生产出口 IP 网络准入 ​

10. 启用 live 模式 Key 并完成上线检查 ​

报障信息清单 ​