API ডকুমেন্টেশন

ভূমিকা

Payman API একটি JSON REST API। সমস্ত অনুরোধ HTTPS এর মাধ্যমে https://payman33.com/v1 এ যায়।

অথেন্টিকেশন

আপনার অ্যাকাউন্ট তৈরি করার সময় প্রাপ্ত অ্যাক্সেস টোকেনটি Bearer টোকেন হিসেবে পাঠান। এটি শুধুমাত্র একবার দেখানো হয় এবং পুনরায় ইস্যু করা যায় না, তাই এটি গোপন রাখুন এবং কখনই ক্লায়েন্ট-সাইড কোডে রাখবেন না।

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

একটি মেসেজ পাঠান

POST /messages

ফিল্ড	টাইপ	বর্ণনা
`to`	string[]	ই.164 ফরম্যাটে প্রাপকরা। প্রতি অনুরোধে সর্বোচ্চ 10,000।
`text`	string	বার্তা বডি: একটি এসএমএস, সর্বোচ্চ 160 অক্ষর (জিএসএম-7), বা 70 যদি এটি অন্য কোনো অক্ষর বা ইমোজি ধারণ করে। দীর্ঘ টেক্সট প্রত্যাখ্যান করা হয়।
`schedule_at`	string	ঐচ্ছিক আইএসও-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 ব্যবহার করুন।

ওয়েবহুক

যখন একটি ডেলিভারি রিপোর্ট আসে আমরা এটি আপনার callback_url এ POST করি। প্রতিটি অনুরোধ একটি X-Payman-Signature হেডার বহন করে: আপনার ওয়েবহুক সিক্রেট (ড্যাশবোর্ড, API ট্যাব) সহ বডির HMAC-SHA256, যাতে আপনি এটি যাচাই করতে পারেন। ব্যর্থ ডেলিভারি ৩ বার পর্যন্ত পুনরায় চেষ্টা করা হয়।

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

ব্যালেন্স

GET /balance

আপনার বর্তমান ব্যালেন্স ইউএসডিটিতে ফেরত দেয়। মূল্য USD তে তালিকাভুক্ত; ১ ইউএসডিটি = ১ 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 প্রাপকের কাছে পাঠাতে পারে।