Tài liệu API SMS

Giới thiệu

Payman API là REST API dùng JSON. Mọi yêu cầu đều gửi đến https://payman33.com/v1 qua HTTPS.

Xác thực

Gửi access token bạn nhận được khi tạo tài khoản dưới dạng bearer token. Token chỉ hiển thị một lần và không thể cấp lại, vì vậy hãy giữ bí mật và không bao giờ đưa vào mã phía client.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Gửi tin nhắn

POST /messages

Trường	Kiểu	Mô tả
`to`	string[]	Người nhận theo định dạng E.164. Tối đa 10,000 mỗi yêu cầu.
`text`	string	Nội dung tin nhắn: một SMS, tối đa 160 ký tự (GSM-7), hoặc 70 nếu chứa bất kỳ chữ cái nào khác hoặc emoji. Văn bản dài hơn sẽ bị từ chối.
`schedule_at`	string	Không bắt buộc. Thời điểm ISO-8601 để gửi sau, tối đa 30 ngày tới.
`callback_url`	string	Không bắt buộc. URL HTTPS nhận báo cáo gửi tin.

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

Thêm header Idempotency-Key để thử lại an toàn: cùng một key trong vòng 24 giờ sẽ trả về phản hồi ban đầu thay vì gửi lại.

Trạng thái tin nhắn

GET /messages/{id}

Các trạng thái: queued, sau đó sent, rồi delivered hoặc failed. Tin nhắn hẹn giờ giữ trạng thái scheduled cho đến khi được gửi; bạn có thể hủy (và được hoàn phí) bằng POST /messages/{id}/cancel.

Webhook

Khi có báo cáo gửi tin, chúng tôi sẽ POST đến callback_url của bạn. Mỗi yêu cầu kèm header X-Payman-Signature: HMAC-SHA256 của nội dung với webhook secret của bạn (Bảng điều khiển, tab API), để bạn có thể xác minh. Nếu gửi thất bại, hệ thống sẽ thử lại tối đa 3 lần.

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

Số dư

GET /balance

Trả về số dư hiện tại bằng USDT. Giá được niêm yết bằng USD; 1 USDT = 1 USD.

Lỗi

HTTP	Mã	Ý nghĩa
400	`invalid_request`	Thiếu trường hoặc trường sai định dạng.
401	`unauthorized`	Thiếu API key hoặc API key không hợp lệ.
402	`insufficient_balance`	Hãy nạp tiền để tiếp tục gửi.
403	`verification_required`	Tài khoản chưa xác minh đã đạt giới hạn người nhận của hôm nay.
404	`not_found`	Không có tin nhắn này trong tài khoản của bạn.
429	`rate_limited`	Quá nhiều yêu cầu. Hãy thử lại sau thời gian ghi trong header `Retry-After`.

Giới hạn tần suất

Giới hạn mặc định là 50 yêu cầu mỗi giây cho mỗi tài khoản. Hãy dùng gửi hàng loạt (nhiều số trong to) cho các chiến dịch lớn. Tài khoản chưa xác minh có thể gửi đến tối đa 500 người nhận mỗi ngày.