Provaho Developer Docs

নিজের ওয়েবসাইটে bKash/Nagad পেমেন্ট নিন — Provaho auto-verify করে অর্ডার confirm করবে। Base URL: https://pay.mhsplanet.com

Quickstart

পাঁচ ধাপে লাইভ:

1Register করুন → 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 করুন
আপনার endpoint 2xx ফেরত দিলে delivered ধরা হয়; নইলে Provaho কয়েকবার retry করে।

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মানে
401API key ভুল/মিসিং
409 no_available_numberওই amount-এর জন্য KYC-approved নম্বর ফ্রি নেই
422ভুল/মিসিং ফিল্ড

সাহায্য দরকার? Dashboard থেকে যোগাযোগ করুন। © Provaho.