服务器 SDK

Paymos 为八个语言生态维护官方服务端 SDK。每个 SDK 覆盖同一套契约：账单、转出、收款通道、通道充值、余额、服务器时间、游标分页、错误、重试、请求签名和 webhook 验证。

八个客户端均已发布到各自生态的包仓库，安装命令见下表；仓库保留源码和发布记录。

语言	包仓库	安装	官方源码
JavaScript / TypeScript	npm	npm i @paymos/sdk	Paymos-labs/typescript-sdk
Python	PyPI	pip install paymos-sdk	Paymos-labs/python-sdk
PHP	Packagist	composer require paymos/php-sdk	Paymos-labs/php-sdk
Go	Go modules	go get github.com/Paymos-labs/go-sdk/v2	Paymos-labs/go-sdk
.NET	NuGet	dotnet add package Paymos	Paymos-labs/dotnet-sdk
Java	Maven Central	io.paymos:paymos-java	Paymos-labs/java-sdk
Ruby	RubyGems	gem install paymos	Paymos-labs/ruby-sdk
Rust	crates.io	cargo add paymos	Paymos-labs/rust-sdk

Java 没有单行安装命令：在 pom.xml 或 Gradle 构建中添加 io.paymos:paymos-java 依赖。

请使用不可变的 vMAJOR.MINOR.PATCH 发布标签。每个仓库的 release 页面包含支持的运行时、变更日志和产生该发布的源码提交。

共享 API 接口

所有客户端暴露六个资源：

• —system——获取服务器时间，用于请求时钟对齐
• —invoices——创建、查询、列出、取消、确认付款和沙箱模拟
• —withdrawals——创建、查询、列出、取消和沙箱完成模拟
• —paymentChannels——创建、查询、列出、封禁、解封和沙箱充值模拟
• —paymentChannelDeposits——读取单笔充值，以及轮询已确认充值流
• —balances——按币种分组列出可用余额

两个通道资源在每种语言里各按自己的命名习惯拼写：TypeScript、PHP 和 Java 是 paymentChannels，Python、Ruby 和 Rust 是 payment_channels，Go 和 .NET 是 PaymentChannels。

列表辅助方法使用游标分页，带最大页数上限，并拒绝被返回两次的游标。自动重试遵循 Retry-After；写操作在传输错误或通用服务器错误时不重试。被限流的请求可以重试，因为 API 并未受理它。

八种语言，一份契约

八个客户端共享的不只是端点清单，还有行为本身。一套与语言无关的一致性用例固定了请求签名要吃进哪些字节、上面那套重试规则、游标迭代器怎么走、webhook 怎么验；SDK 只有自己的测试跑通这套用例，才会发版。

实际的好处是：把一套集成从其中一种语言搬到另一种，签名、翻页、重试和 webhook 语义都跟着过去。同一个带筛选条件的列表请求，两个 SDK 签出来的字节一致。

PHP 多出来的一层

PHP SDK 带有一层其他客户端都没有的商城对接逻辑：拿 webhook 回头向 API 重新读一次做反向校验、放行订单前核对金额与币种、用可替换的事件存储做重放去重、一个同时握着 Sandbox 与正式 secret 的验证器、对账、把事件映射成订单动作，以及加密保存凭证。

CMS 插件之所以这么薄，就是因为这一层：订单状态的逻辑在它们下面的 SDK 里写了一次，而不是在上面写八次。其余七个客户端不适用这一段——它们只有客户端、签名、资源、分页和 webhook 验证，再多就没有了。

安全规则

请求认证和 webhook 认证使用不同的签名。API 请求用 base64 HMAC-SHA256 对规范请求签名；webhook 用十六进制 HMAC-SHA256 对 {timestamp}.{精确原始 body} 签名。把未解析的请求字节传给 SDK 验证器后再解码 JSON。验证器默认拒绝与当前时间相差超过五分钟的时间戳，并接受带两个 v1 值的请求头，所以更换 secret 不需要你改代码。

端点模式和示例请继续阅读 认证、账单、转出、余额 和 Webhooks。