1. TLY Pay API
简体中文
  • English
  • 简体中文
  • TLY Pay API
    • 快速开始
    • HTTP 约定和支付状态
    • Webhook 验签和恢复
    • 支付接入
      • 创建 Payment
      • 查询 Payment 状态
      • 取消 Payment
      • 关闭 Checkout 访问
      • 检查计价配置
      • 配置 Webhook
      • 验证 Webhook 签名密钥
  • Schemas
    • BootstrapWebhook
    • CreatePayment
    • CreatedPayment
    • ErrorResponse
    • MerchantPaymentView
    • MerchantSourceAmountView
    • MerchantStoreSourceView
    • MerchantStoreView
    • OneTimeSecretResponse
    • SourceAmount
    • VerifyWebhookBinding
    • WebhookBindingView
  1. TLY Pay API

快速开始

本文档面向在应用中集成 TLY Pay 支付的开发者. 在服务端调用 TLY Pay API 创建 Payment, 打开 Hosted Checkout 或 Embedded Checkout, 再通过已验签的 Webhook 或权威查询核对支付结果.
Payment 是支付记录, 在 TLY Pay 后台的 支付 页面查看. 创建支付链接 操作生成用于打开 Hosted Checkout 的 支付链接. 客户通过 Hosted Checkout 或 Embedded Checkout 付款, 两种方式使用同一 Payment.

配置 TLY Pay 账户#

在 TLY Pay 后台完成以下配置:
1.
登录并完成账户注册.
2.
打开 设置 > 付款设置. 如果没有已验证的收款 Wallet, 选择 连接 Wallet, 为 Wallet 命名, 再在 TLY Wallet 中批准一次连接. 验证会自动完成. 已连接且已验证的 Wallet 可以直接复用. 显示货币 只改变 Wallet 估算价值的显示方式, 不改变 Payment 计价或可接受的支付资产.
3.
打开 Checkout. 在 已启用的网络和币种 中确认已为该 Wallet 启用的币种. 这些是消费者可以用于支付的币种.
4.
使用 Embedded Checkout 时, 在同一 Checkout 页面的 网站(可选) 配置网站的 HTTPS Origin. Hosted Checkout 不要求此项.
5.
打开 集成 > API 密钥, 选择 签发 API Key. 此操作自动签发下列标准作用域. 在 保存此 API 密钥 中保存凭据; 已有凭据无法再次显示.
6.
使用支付通知时, 先准备接收器, 再打开 集成 > Webhook > 添加 Webhook, 填写接收器的公开 HTTPS URL 并保存签名密钥. 验签和轮换请参考单独的 Webhook 指南.
Wallet 连接通过 TLY Wallet 完成批准和控制权证明. 你的服务端和客户不需要使用 Wallet 凭据. 只读的 Wallet 余额和地址展示不要求安装扩展.
API 密钥的标准作用域为:
payment:write: 创建或取消 Payment, 关闭 Checkout 访问.
payment:read: 查询支付状态, 校验计价配置.
webhook:bootstrap: 配置 Webhook, 验证签名密钥.
API 密钥和 Webhook 签名密钥必须保存在服务端. 使用 Authorization: Bearer <API_KEY>, 不得将 API 密钥放入浏览器代码, URL, 截图或日志. 更换 API 密钥时, 先签发新 API 密钥, 部署并验证后, 再在 TLY Pay 后台撤销旧 API 密钥.
使用为当前集成提供的 TLY Pay API 和 Checkout Origin. 示例从服务端配置读取 TLY_API_ORIGIN 和 TLY_API_KEY. 将 HOSTED_CHECKOUT_ORIGIN 配置为提供的 Checkout Origin.

API Origin#

API 地址为 https://api.tlypay.com. API 密钥必须保存在服务端配置中.

校验计价并创建 Payment#

构造请求前, 使用 API 密钥调用 GET /v1/store 校验已配置的计价来源和网站域名. 根据返回的 primary_source kind, ref 和 decimals 构造 source_amount. 不得根据 显示货币 或消费者支付的资产推断 Payment 计价.
curl --request POST "${TLY_API_ORIGIN}/v1/payments" \
  --header "Authorization: Bearer ${TLY_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-example-1048" \
  --data '{"order_ref":"ORDER-EXAMPLE-1048","source_amount":{"kind":"fiat","currency":"USD","amount_raw":"12800"}}'
所有示例值仅用于说明. source_amount 必须匹配配置的主计价来源. USD 12800 表示 USD 128.00. 金额使用无前导零的正整数字符串, 不使用浮点数, 小数位数由服务确定. 使用加密资产计价时, 提供 kind: "crypto", 已配置的 pricing_ref 和 amount_raw; 不得用 Token 合约地址或网络 ID 替代 Pricing ref.
order_ref 是可选字段, 不具有唯一性. 每次创建意图保持一个固定的 Idempotency-Key, 超时后重试必须复用同一幂等键和相同请求体. 首次创建成功或相同请求的幂等重放均返回 HTTP 200, 不返回 201. 创建 Payment 不会将订单标记为已支付.
将返回的 payment_id 与你的订单一起保存. 用它打开 Checkout, 查询支付状态, 或在联系客服时标识这笔 Payment. 你和客户使用同一个 ID, 可以展示和复制. Checkout 仍受网站授权, 风控, 到期和访问限制约束. 服务端查询和修改 Payment 需要 API 密钥.

打开 Checkout 并核对订单#

使用 HOSTED_CHECKOUT_ORIGIN 和 /#payment_id=<payment_id> 打开 Hosted Checkout. 使用 Embedded Checkout 时, 在网站上单次加载提供的 /widget/crypto-pay.js Embedded Checkout 脚本, 使用返回的 Payment ID 调用 window.CryptoPay.open({ paymentId }). Hosted Checkout URL 的片段中携带同一个 ID. 客户打开 Checkout 后开始付款; 仅创建链接不能证明支付成功.
Embedded Checkout 脚本 在提供的 Checkout Origin 处理支付请求. 集成服务端继续在 TLY_API_ORIGIN 调用 /v1/*; 不要将 API 密钥暴露给浏览器代码.
使用 Embedded Checkout 时, 在创建请求中通过 checkout_origin 提交 网站(可选) 允许的 HTTPS Origin. 省略该字段时使用已配置的 Hosted Checkout Origin. 仅在 TLY Pay 后台保存网站不会改变通过 API 创建的 Payment 的 Origin.
配置带签名的 payment.updated Webhook, 或使用具备 payment:read 作用域的 API 密钥, 在服务端调用 GET /v1/payments/{payment_id}. 查询响应表达权威支付事实. 浏览器跳转或 Webhook 投递结果均不构成支付凭证.
仅根据权威状态和业务异常处理策略履约. 必须明确处理部分支付, 超额支付和需要审核的支付. Webhook 可能重复或乱序到达, 按 Webhook 指南使用 Event ID 和对应 Payment 的 status_version.
如果集成使用权威查询替代通知, Webhook 交互可以省略. 状态事件也可能表达未完成或异常支付, 不能仅因收到事件就履约. Hosted Checkout 和 Embedded Checkout 使用相同的支付事实.

可选操作#

使用 POST /v1/payments/{payment_id}/cancel 取消仍为 open, 未过期且没有已接受或确认中资金的 Payment. 重复成功取消会读取当前状态.
使用 DELETE /v1/payments/{payment_id}/consumer-access 关闭 Checkout 访问. 客户将无法再通过 Checkout 访问这笔 Payment. 支付状态不变, 你的服务端仍可查询.
使用 GET /v1/store 校验 API 密钥配置的计价来源和网站域名.
API 密钥管理位于 集成 > API 密钥. Wallet 连接和 显示货币 位于 设置 > 付款设置; 已启用的网络和币种 和 网站(可选) 位于 Checkout. Webhook 管理位于 集成 > Webhook.
Next
HTTP 约定和支付状态
Built with