Dokumentasi API

Pendahuluan

Payman API adalah JSON REST API. Semua permintaan dikirim ke https://payman33.com/v1 melalui HTTPS.

Autentikasi

Kirim token akses yang Anda terima saat membuat akun sebagai bearer token. Token hanya ditampilkan sekali dan tidak dapat diterbitkan ulang, jadi jaga kerahasiaannya dan jangan pernah menaruhnya di kode sisi klien.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Kirim pesan

POST /messages

Field	Tipe	Deskripsi
`to`	string[]	Penerima dalam format E.164. Hingga 10.000 per permintaan.
`text`	string	Isi pesan: satu SMS, hingga 160 karakter (GSM-7), atau 70 jika berisi huruf lain atau emoji. Teks yang lebih panjang ditolak.
`schedule_at`	string	Opsional. Waktu ISO-8601 untuk mengirim nanti, hingga 30 hari ke depan.
`callback_url`	string	Opsional. URL HTTPS yang menerima laporan pengiriman.

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

Tambahkan header Idempotency-Key agar aman saat mencoba ulang: key yang sama dalam 24 jam mengembalikan respons asli alih-alih mengirim ulang.

Status pesan

GET /messages/{id}

Status: queued, lalu sent, lalu delivered atau failed. Pesan terjadwal tetap berstatus scheduled sampai dikirim; batalkan (dan dapatkan kembali biayanya) dengan POST /messages/{id}/cancel.

Webhook

Saat laporan pengiriman tiba, kami mengirimkannya dengan POST ke callback_url Anda. Setiap permintaan menyertakan header X-Payman-Signature, yaitu HMAC-SHA256 dari body dengan rahasia webhook Anda (Dasbor, tab API), agar Anda dapat memverifikasinya. Pengiriman yang gagal dicoba ulang hingga 3 kali.

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

Saldo

GET /balance

Mengembalikan saldo Anda saat ini dalam USDT. Harga tercantum dalam USD; 1 USDT = 1 USD.

Error

HTTP	Kode	Arti
400	`invalid_request`	Field tidak ada atau formatnya salah.
401	`unauthorized`	Kunci API tidak ada atau tidak valid.
402	`insufficient_balance`	Isi saldo untuk melanjutkan pengiriman.
403	`verification_required`	Akun yang belum diverifikasi telah mencapai batas penerima hari ini.
404	`not_found`	Pesan tersebut tidak ada di akun Anda.
429	`rate_limited`	Terlalu banyak permintaan. Coba lagi setelah waktu di header `Retry-After`.

Batas permintaan

Batas default adalah 50 permintaan per detik per akun. Gunakan pengiriman massal (beberapa nomor di to) untuk kampanye besar. Akun yang belum diverifikasi dapat mengirim ke hingga 500 penerima per hari.