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 個收件人發送。