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 位收件人。