OraclePay (OPay) API Docs

সহজ, রিয়েলটাইম এবং প্রিমিয়াম পেমেন্ট ইন্টিগ্রেশন গেটওয়ে ডকুমেন্টেশন

🔗 মূল API বেস ইউআরএল (Main API Base URL)

আপনার সমস্ত API রিকোয়েস্ট এবং কনেকশনের জন্য নিচের মূল বেস ইউআরএল (Base URL) ব্যবহার করুন:

https://api.oraclepay.org

⚠️ ইন্টিগ্রেশন শুরু করার আগের প্রস্তুতি (Personal OPay Panel Setup Guide)

আপনার ওয়েবসাইটে বা অ্যাপে API ইন্টিগ্রেশন করার পূর্বে আপনাকে অবশ্যই OraclePay (OPay) Mobile App অথবা ওপে পার্সোনাল ওয়েব পোর্টালে লগইন করে নিচের কাজগুলো সম্পন্ন করতে হবে:

১. লগইন এবং প্রোফাইল চেক (Login & Profile) প্রথমে OPay মোবাইল অ্যাপ বা পার্সোনাল প্যানেলে লগইন করুন। Account & Support -> My Profile-এ গিয়ে আপনার নাম এবং প্রোফাইলের তথ্য সঠিক আছে কিনা নিশ্চিত হয়ে Save Changes দিন। প্রয়োজনে পাসওয়ার্ড পরিবর্তন করে নিন।
২. ডিভাইস যুক্ত করা (Device Management) প্যানেলের Device Management -> My Devices মেন্যুতে যান। এরপর Add Device বাটনে ক্লিক করে আপনার ডিভাইসের একটি সুন্দর নাম দিয়ে ডিভাইসটি যুক্ত (Add) করুন।
৩. পেমেন্ট নম্বর যুক্ত করা (Payment Methods Setup) এবার Integration -> Payment Methods মেন্যুতে গিয়ে আপনার ডিভাইসটি সিলেক্ট করুন। তারপর আপনার বিকাশ (bKash), নগদ (Nagad), রকেট (Rocket) অথবা উপায় (Upay) নম্বরগুলো পার্সোনাল নাকি এজেন্ট সিলেক্ট করে অ্যাড করুন।
৪. পেমেন্ট পেজ তৈরি করা (Payment Pages Setup) Integration -> Payment Pages মেন্যুতে যান। আপনার যুক্ত করা নম্বরগুলোর জন্য একটি পেমেন্ট পেজ তৈরি করুন। এখানে মেথডের নাম, ডিপোজিট মেথড, কাস্টমার নোট, নগদ/বিকাশ/রকেটের ব্র্যান্ড ইমেজ, গুরুত্বপূর্ণ নোটিশ, থিম কালার (যেমন ব্যাকগ্রাউন্ড কালার, টেক্সট কালার, বাটন কালার) এবং পেমেন্টের বিস্তারিত বিবরণ (যেমন: প্রথমে বিকাশ অ্যাপ ওপেন করুন ইত্যাদি) লিখে পেমেন্ট পেজটি তৈরি করুন।
৫. কাস্টমার সাপোর্ট নম্বর সেটআপ (Support Ticket Setting) Account & Support -> Support Ticket মেন্যুতে যান। সেখানে Add Support Number বাটনে ক্লিক করে আপনার হেল্পলাইন বা সাপোর্ট নম্বরটি যুক্ত করুন। এই নম্বরটিই ডিভাইস অফলাইন থাকলে কাস্টমারকে দেখানো হবে।
৬. API Key ও সাবস্ক্রিপশন জেনারেট (Generate API Key) সর্বশেষে, Integration -> API Key মেন্যুতে গিয়ে আপনার active প্ল্যান/প্যাকেজ এবং ডিভাইসটি সিলেক্ট করুন। আপনার নিজস্ব সার্ভারের Webhook Callback URL (যা অবশ্যই https:// হতে হবে) দিন এবং Generate API Key বাটনে ক্লিক করে আপনার সিকিউর API Key তৈরি করে নিন।

🔄 ডেভেলপার ইন্টিগ্রেশন ফ্লো (Interactive Steps & Visual Flow)

OraclePay API ইন্টিগ্রেশনের সময় কোন এন্ডপয়েন্টের পর কোনটি কল করবেন, তা নিচে অ্যানিমেটেড ভিজ্যুয়াল ডায়াগ্রাম এবং বিস্তারিত গাইডের মাধ্যমে দেখানো হলো:

Step 1: ভ্যালিডেশন 🔑 API Key ভ্যালিড করুন
Step 2: ডিভাইস চেকিং 📱 ডিভাইস অনলাইন নাকি অফলাইন?
🔴 অফলাইন হলে
Step 2.1: কাস্টমার সাপোর্ট 📞 সাপোর্ট নম্বর দেখান
🟢 অনলাইন হলে
Step 3: পেমেন্ট পেজ 💳 পেমেন্ট পেজ জেনারেট করুন
Step 4: সাকসেস নোটিফিকেশন 🔔 Webhook কলব্যাক রিসিভ

🎯 ১. API Key ভ্যালিডেশন

সিস্টেম সচল করার সময় /api/external/key/validate কল করে API Key ও সাবস্ক্রিপশন সচল আছে কিনা চেক করে নিন।

📱 ২. ডিভাইস অনলাইন/অফলাইন চেক

Socket.IO দিয়ে ডিভাইস স্ট্যাটাস রিয়েলটাইমে পর্যবেক্ষণ করুন। ডিভাইস অফলাইন হলে গ্রাহককে মার্চেন্টের সাপোর্ট নম্বর দেখানোর জন্য /api/external/support-number এন্ডপয়েন্টটি ব্যবহার করুন। ডিভাইস অনলাইন থাকলে পেমেন্ট গেটওয়েতে যান।

💳 ৩. পেমেন্ট পেজ জেনারেট

ডিভাইস অনলাইন থাকলে /api/external/generate এন্ডপয়েন্ট ব্যবহার করে পেমেন্ট পেজ জেনারেট লিংকে কাস্টমারকে নিয়ে যান।

🔔 ৪. Webhook কলব্যাক

পেমেন্ট সম্পূর্ণ হওয়ার পর ওপে সার্ভার স্বয়ংক্রিয়ভাবে মার্চেন্ট কলব্যাক ইউআরএলে পেমেন্ট সফলতার নোটিফিকেশন পাঠাবে ও ডাটাবেজ আপডেট হবে।

১. অথেন্টিকেশন (Authentication)

OraclePay-এর এন্ডপয়েন্টগুলোতে রিকোয়েস্ট করতে HTTP হেডারে আপনার API Key সংযুক্ত করুন:

X-API-Key: YOUR_API_KEY_HERE

২. API Key ভ্যালিডেশন (Key Validate)

আপনার API Key, সাবস্ক্রিপশন প্ল্যান, এবং পেমেন্ট নম্বরগুলোর স্ট্যাটাস চেক করুন।

GET /api/external/key/validate
const axios = require('axios');

async function validateApiKey() {
  try {
    const response = await axios.get('https://api.oraclepay.org/api/external/key/validate', {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    console.log("Success:", response.data);
  } catch (error) {
    console.error("Error:", error.response ? error.response.data : error.message);
  }
}
validateApiKey();
async function validateApiKey() {
  try {
    const res = await fetch('https://api.oraclepay.org/api/external/key/validate', {
      method: 'GET',
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    const data = await res.json();
    console.log(data);
  } catch (err) {
    console.error(err);
  }
}
validateApiKey();
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.oraclepay.org/api/external/key/validate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: YOUR_API_KEY"
]);

$response = curl_exec($ch);
if(curl_errno($ch)){
    echo 'Curl error: ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    print_r($data);
}
curl_close($ch);
?>

৩. পেমেন্ট পেজ জেনারেট (Generate Payment Page)

কাস্টমারের জন্য পেমেন্ট পেজ তৈরি করতে এই API কল করুন।

GET /api/external/generate
Parameter Type Status Description methods String Required পেমেন্ট মেথড যেমন: bkash,nagad,rocket,upay amount Number Required পেমেন্টের পরিমাণ (অবশ্যই > ০) userIdentifyAddress String Required মার্চেন্ট অর্ডার আইডি বা ট্র্যাকিং এড্রেস
const axios = require('axios');

async function generatePayment() {
  try {
    const response = await axios.get('https://api.oraclepay.org/api/external/generate', {
      params: {
        methods: 'bkash,nagad',
        amount: 350,
        userIdentifyAddress: 'ORDER-2025-0001'
      },
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    console.log("Payment Page URL:", response.data.payment_page_url);
  } catch (error) {
    console.error(error.response ? error.response.data : error.message);
  }
}
generatePayment();
async function generatePayment() {
  const url = 'https://api.oraclepay.org/api/external/generate?methods=bkash,nagad&amount=350&userIdentifyAddress=ORDER-2025-0001';
  const res = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await res.json();
  console.log(data.payment_page_url);
}
generatePayment();
<?php
$queryParams = http_build_query([
    'methods' => 'bkash,nagad',
    'amount' => 350,
    'userIdentifyAddress' => 'ORDER-2025-0001'
]);
$url = "https://api.oraclepay.org/api/external/generate?" . $queryParams;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: YOUR_API_KEY"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Payment URL: " . $data['payment_page_url'];
curl_close($ch);
?>

৪. রিয়েলটাইম ডিভাইস ট্র্যাকিং (Device Presence)

আপনার ডিভাইসগুলো অনলাইন/অফলাইন কিনা তা Socket.IO এর মাধ্যমে ট্র্যাক করুন।

SOCKET.IO https://api.oraclepay.org (Transports: ['websocket'])
const { io } = require("socket.io-client");

const socket = io("https://api.oraclepay.org", {
  transports: ["websocket"]
});

socket.on("connect", () => {
  socket.emit("viewer:registerApiKey", { apiKey: "YOUR_API_KEY" });
});

socket.on("viewer:devices", (devicesList) => {
  console.log("Snapshot Devices:", devicesList);
});

socket.on("viewer:device", (device) => {
  console.log(`Device updated: ${device.deviceId} is ${device.active ? 'Online' : 'Offline'}`);
});

socket.on("viewer:error", (err) => console.error(err));
<script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
<script>
  const socket = io("https://api.oraclepay.org", { transports: ["websocket"] });

  socket.on("connect", () => {
    socket.emit("viewer:registerApiKey", { apiKey: "YOUR_API_KEY" });
  });

  socket.on("viewer:devices", (list) => {
    console.log("Snapshot", list);
  });

  socket.on("viewer:device", (d) => {
    console.log("Device update", d.deviceId, d.active ? "Online" : "Offline");
  });
</script>

৫. সাপোর্ট নম্বর পুনরুদ্ধার (Support Number)

আপনার মার্চেন্ট অ্যাকাউন্টের অফিশিয়াল সাপোর্ট নম্বর ফেরত দেয়।

GET /api/external/support-number
const axios = require('axios');
axios.get('https://api.oraclepay.org/api/external/support-number', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(res => console.log("Support Number:", res.data.supportNumber))
  .catch(err => console.error(err));
<?php
$ch = curl_init("https://api.oraclepay.org/api/external/support-number");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
$res = curl_exec($ch);
$data = json_decode($res, true);
echo "Support Number: " . $data['supportNumber'];
curl_close($ch);
?>

৬. পেমেন্ট সাকসেস ওয়েবহুক (Payment Webhook)

পেমেন্ট সফল হলে আপনার সিস্টেমে পাঠানো JSON ডাটা রিসিভ করুন।

POST YOUR_CALLBACK_URL
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/payment-verified', (req, res) => {
  const paymentData = req.body;
  if (paymentData.success) {
    console.log(`Payment success: Order ${paymentData.userIdentifyAddress}, Amount ${paymentData.amount}`);
    // সফল পেমেন্ট অনুযায়ী আপনার ডাটাবেজ আপডেট করুন
  }
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Listening for Webhooks'));
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $json = file_get_contents('php://input');
    $paymentData = json_decode($json, true);

    if ($paymentData && $paymentData['success']) {
        $orderId = $paymentData['userIdentifyAddress'];
        $amount = $paymentData['amount'];
        $trxId = $paymentData['trxid'];
        
        // এখানে ডাটাবেজ সফল করার কুয়েরি রান করুন
        
        http_response_code(200);
        echo "OK";
    }
}
?>