Dokumentasi API

Pengenalan

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

Pengesahan

Hantar token akses yang anda terima semasa membuat akaun sebagai token bearer. Ia hanya dipaparkan sekali dan tidak boleh dikeluarkan semula, jadi simpan dengan rahsia dan jangan letak dalam kod pelanggan.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Hantar mesej

POST /messages

Medan	Jenis	Keterangan
`to`	string[]	Penerima dalam format E.164. Maksimum 10,000 setiap permintaan.
`text`	string	Isi mesej: satu SMS, maksimum 160 aksara (GSM-7), atau 70 jika mengandungi huruf atau emoji lain. Teks lebih panjang akan ditolak.
`schedule_at`	string	Pilihan masa ISO-8601 untuk hantar kemudian, sehingga 30 hari hadapan.
`callback_url`	string	Pilihan URL HTTPS yang menerima laporan penghantaran.

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

Tambah header Idempotency-Key untuk mencuba semula dengan selamat: kunci yang sama dalam 24 jam mengembalikan respons asal bukannya menghantar semula.

Status mesej

GET /messages/{id}

Status: queued, kemudian sent, kemudian delivered atau failed. Mesej berjadual kekal scheduled sehingga dihantar; batalkan (dan dapatkan bayaran balik) dengan POST /messages/{id}/cancel.

Webhook

Apabila laporan penghantaran tiba, kami POST ke callback_url anda. Setiap permintaan mengandungi header X-Payman-Signature: HMAC-SHA256 badan dengan rahsia webhook anda (Dashboard, tab API), untuk pengesahan. Penghantaran gagal akan dicuba sehingga 3 kali.

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

Baki

GET /balance

Mengembalikan baki semasa dalam USDT. Harga disenaraikan dalam USD; 1 USDT = 1 USD.

Ralat

HTTP	Kod	Maksud
400	`invalid_request`	Medan hilang atau tidak betul.
401	`unauthorized`	Kunci API hilang atau tidak sah.
402	`insufficient_balance`	Isi semula untuk terus menghantar.
403	`verification_required`	Akaun yang tidak disahkan telah mencapai had penerima hari ini.
404	`not_found`	Tiada mesej sedemikian pada akaun anda.
429	`rate_limited`	Terlalu banyak permintaan. Cuba semula selepas header `Retry-After`.

Had kadar

Had lalai ialah 50 permintaan sesaat setiap akaun. Gunakan penghantaran pukal (berbilang nombor dalam to) untuk kempen besar. Akaun tidak disahkan boleh menghantar kepada maksimum 500 penerima sehari.