API 文档 | Payman

简介

Payman API 是一个 JSON REST API。所有请求均通过 HTTPS 发送至 https://payman33.com/v1。

将创建账户时获得的访问令牌作为 bearer 令牌发送。令牌仅显示一次且无法重新签发，请妥善保密，切勿放在客户端代码中。

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

POST /messages

字段	类型	说明
`to`	string[]	E.164 格式的收件人号码。每次请求最多 10,000 个。
`text`	string	消息正文：一条短信，最多 160 个字符（GSM-7），如包含任何其他字母或表情符号则为 70 个。超长文本将被拒绝。
`schedule_at`	string	可选。ISO-8601 格式的定时发送时间，最多可提前 30 天。
`callback_url`	string	可选。接收送达报告的 HTTPS URL。

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

添加 Idempotency-Key 请求头即可安全重试：24 小时内使用相同的键将返回原始响应，而不会重复发送。

GET /messages/{id}

状态依次为：queued，然后 sent，最后 delivered 或 failed。定时消息在发出前保持 scheduled 状态；可通过 POST /messages/{id}/cancel 取消（并退还费用）。

收到送达报告后，我们会将其 POST 到您的 callback_url。每个请求都带有 X-Payman-Signature 请求头，即使用您的 Webhook 密钥（控制台的 API 标签页）对请求体计算的 HMAC-SHA256，供您验证。推送失败最多重试 3 次。

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

GET /balance

返回您当前的 USDT 余额。价格以 USD 计；1 USDT = 1 USD。

HTTP	代码	含义
400	`invalid_request`	字段缺失或格式错误。
401	`unauthorized`	API 密钥缺失或无效。
402	`insufficient_balance`	请充值后继续发送。
403	`verification_required`	未认证账户已达到今日收件人上限。
404	`not_found`	您的账户中不存在该消息。
429	`rate_limited`	请求过多。请在 `Retry-After` 请求头指定的时间后重试。

默认限制为每个账户每秒 50 个请求。大型营销活动请使用批量发送（在 to 中填写多个号码）。未认证账户每天最多可向 500 个收件人发送。