Provaho Developer Docs
নিজের ওয়েবসাইটে bKash/Nagad পেমেন্ট নিন — Provaho auto-verify করে অর্ডার confirm করবে। Base URL: https://pay.mhsplanet.com
Quickstart
পাঁচ ধাপে লাইভ:
| 1 | Register করুন → dashboard থেকে একটা API key (sk_test_…) নিন। |
| 2 | আপনার bKash/Nagad নম্বর যোগ করুন ও KYC approve করান (Numbers & KYC)। |
| 3 | একটা ফোনে Provaho অ্যাপ বসিয়ে activate করুন (verifier)। |
| 4 | নিজের server থেকে একটা session বানান → গ্রাহককে checkout_url-এ পাঠান। |
| 5 | পেমেন্ট verify হলে আপনার webhook-এ session.paid আসবে → অর্ডার confirm। |
Authentication
প্রতিটা API কল-এ API key পাঠান Bearer হিসেবে:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
sk_test_… = টেস্ট, sk_live_… = লাইভ। Key কখনো ব্রাউজার/ফ্রন্টএন্ডে রাখবেন না — শুধু আপনার server থেকে কল করুন।
Create a payment session
POST/api/v1/sessions
একটা অর্ডারের জন্য পেমেন্ট session তৈরি করে। Provaho একটা KYC-approved নম্বর বেছে দেয় আর একটা hosted checkout URL ফেরত দেয়।
Request
POST /api/v1/sessions Authorization: Bearer sk_test_••• Content-Type: application/json { "order_id": "INV-1001", // আপনার অর্ডার আইডি (required) "provider": "bkash", // bkash | nagad | rocket | upay "amount": 500, // টাকায় (required) "currency": "BDT", // optional "customer_ref": "cus_01", // optional "sender_hint": "01XXXXXXXXX", // optional — গ্রাহকের নম্বর (দ্রুত match) "success_url": "https://shop.com/ok", "cancel_url": "https://shop.com/cancel", "webhook_url": "https://shop.com/provaho-hook", "expiry_seconds": 1800 // optional (300–7200) }
Response 201
{
"id": "ses_abc123",
"status": "PENDING",
"provider": "bkash",
"pay_to_number": "01XXXXXXXXX", // গ্রাহক এই নম্বরে পাঠাবে
"amount": "500.00",
"currency": "BDT",
"expires_at": "2026-10-02T12:00:00+00:00",
"checkout_url": "https://pay.mhsplanet.com/checkout/ses_abc123"
}
checkout_url-এ redirect করুন — অথবা pay_to_number + amount নিয়ে নিজের পেজ বানান।Check session status
GET/api/v1/sessions/{id}
webhook ছাড়াও status নিজে poll করতে পারেন। status: PENDING · PAID · REVIEW · EXPIRED · REJECTED।
GET /api/v1/sessions/ses_abc123
Authorization: Bearer sk_test_•••
Hosted checkout
সবচেয়ে সহজ উপায় — কোড কম। session বানিয়ে গ্রাহককে checkout_url-এ পাঠান। ওই পেজে গ্রাহক কোন নম্বরে কত পাঠাবে দেখে, পেমেন্ট করে, আর Provaho আপনার ফোন দিয়ে auto-verify করে। হয়ে গেলে গ্রাহক success_url-এ ফেরে ও আপনার webhook-এ session.paid যায়।
Webhooks
ঘটনা ঘটলে Provaho আপনার URL-এ POST করে। Events:
| Event | কখন |
|---|---|
session.paid | পেমেন্ট মিলে গেছে ✓ — অর্ডার confirm করুন |
session.review | দ্ব্যর্থতা/ফ্ল্যাগ — ম্যানুয়াল দেখা দরকার |
session.expired | সময় শেষ, পেমেন্ট আসেনি |
session.rejected | বাতিল/ডুপ্লিকেট |
Payload
{
"event": "session.paid",
"order_id": "INV-1001",
"session": "ses_abc123",
"amount": "500.00",
"provider": "bkash",
"trx_id": "DJ289PSF92",
"at": "2026-10-02T11:59:00+00:00"
}
Webhook signature verify করুন
প্রতিটা webhook-এ একটা header থাকে:
X-Signature: t=1730000000,v1=<hmac>
v1 = HMAC-SHA256(webhook_secret, "{t}.{raw_request_body}")। আপনার endpoint secret দিয়ে মিলিয়ে নিন (replay এড়াতে t খুব পুরোনো হলে বাতিল করুন):
// PHP $raw = file_get_contents('php://input'); [$t, $v1] = sscanf($_SERVER['HTTP_X_SIGNATURE'], "t=%d,v1=%s"); $expected = hash_hmac('sha256', $t . '.' . $raw, $WEBHOOK_SECRET); if (!hash_equals($expected, $v1) || abs(time() - $t) > 300) { http_response_code(400); exit; // জাল/পুরোনো } $event = json_decode($raw, true); // $event['event'] === 'session.paid' হলে অর্ডার confirm করুন
Payouts (disburse)
POST/api/v1/payouts
গ্রাহককে টাকা পাঠান (send-money) — refund বা commission-ও এভাবে। Provaho balance ও priority দেখে আপনার কোন নম্বর থেকে পাঠাবে ঠিক করে।
POST /api/v1/payouts Authorization: Bearer sk_live_••• { "reference": "REF-9001", // idempotent "provider": "bkash", "amount": 500, "receiver": "01XXXXXXXXX" }
Status নিন: GET/api/v1/payouts/{id}। COMPLETED কেবল তখনই যখন আপনার ওয়ালেটের outgoing SMS নিশ্চিত করে (double-pay নিরাপত্তা)।
Test mode
sk_test_… key দিয়ে সব API কাজ করে — আসল টাকা ছাড়া। লাইভে যেতে sk_live_… key ব্যবহার করুন।
Errors
| Code | মানে |
|---|---|
401 | API key ভুল/মিসিং |
409 no_available_number | ওই amount-এর জন্য KYC-approved নম্বর ফ্রি নেই |
422 | ভুল/মিসিং ফিল্ড |
সাহায্য দরকার? Dashboard থেকে যোগাযোগ করুন। © Provaho.