API belgeleri | Payman

Giriş

Payman API, bir JSON REST API'dir. Tüm istekler HTTPS üzerinden https://payman33.com/v1 adresine gönderilir.

Kimlik doğrulama

Hesabınızı oluştururken aldığınız erişim anahtarını bearer token olarak gönderin. Yalnızca bir kez gösterilir ve yeniden verilemez, bu yüzden gizli tutun ve asla istemci tarafı koda koymayın.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Mesaj gönderme

POST /messages

Alan	Tür	Açıklama
`to`	string[]	E.164 biçiminde alıcılar. İstek başına en fazla 10.000.
`text`	string	Mesaj metni: tek bir SMS, en fazla 160 karakter (GSM-7), başka harf veya emoji içeriyorsa 70. Daha uzun metin reddedilir.
`schedule_at`	string	İsteğe bağlı. Daha sonra göndermek için ISO-8601 biçiminde zaman, en fazla 30 gün sonrası.
`callback_url`	string	İsteğe bağlı. Teslim raporlarını alacak HTTPS URL'si.

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

Güvenle yeniden denemek için bir Idempotency-Key başlığı ekleyin: 24 saat içinde aynı anahtar, yeniden göndermek yerine orijinal yanıtı döndürür.

Mesaj durumu

GET /messages/{id}

Durumlar: önce queued, sonra sent, ardından delivered veya failed. Zamanlanmış bir mesaj gönderilene kadar scheduled durumunda kalır; POST /messages/{id}/cancel ile iptal edebilir (ve ücreti geri alabilirsiniz).

Webhook'lar

Bir teslim raporu geldiğinde onu callback_url adresinize POST ederiz. Doğrulayabilmeniz için her istek bir X-Payman-Signature başlığı taşır: gövdenin webhook gizli anahtarınızla (Panel, API sekmesi) hesaplanan HMAC-SHA256 değeri. Başarısız iletimler en fazla 3 kez yeniden denenir.

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

Bakiye

GET /balance

Mevcut bakiyenizi USDT olarak döndürür. Fiyatlar USD cinsindendir; 1 USDT = 1 USD.

Hatalar

HTTP	Kod	Anlamı
400	`invalid_request`	Eksik veya hatalı biçimlendirilmiş alan.
401	`unauthorized`	Eksik veya geçersiz API anahtarı.
402	`insufficient_balance`	Göndermeye devam etmek için bakiye yükleyin.
403	`verification_required`	Doğrulanmamış hesap bugünkü alıcı sınırına ulaştı.
404	`not_found`	Hesabınızda böyle bir mesaj yok.
429	`rate_limited`	Çok fazla istek. `Retry-After` başlığında belirtilen süreden sonra yeniden deneyin.

Hız sınırları

Varsayılan sınır hesap başına saniyede 50 istektir. Büyük kampanyalar için toplu gönderim kullanın (to içinde birden fazla numara). Doğrulanmamış hesaplar günde en fazla 500 alıcıya gönderebilir.