নিরাপদ ও প্রোডাকশন-রেডি API ইন্টিগ্রেশন ডকুমেন্টেশন

রিচার্জ API ইন্টিগ্রেশন গাইডলাইন ও সম্পূর্ণ রেসপন্স ডকুমেন্টেশন

এই API ব্যবহার করে আপনার ওয়েবসাইট, সফটওয়্যার বা অ্যাপ থেকে নিরাপদভাবে মোবাইল রিচার্জ করা যাবে। API ব্যবহারের জন্য সঠিক API Key, Secret Key, অপারেটর, মোবাইল নম্বর, পরিমাণ এবং account_type পাঠাতে হবে। এছাড়া Domain, IP, Account Status এবং Business/Company Profile Approval যাচাই করা হবে।

এন্ডপয়েন্ট দেখুন উদাহরণ কোড দেখুন

এন্ডপয়েন্ট প্যারামিটার শর্তাবলি উদাহরণ সফল রেসপন্স এরর কোড ত্রুটি রেসপন্স

রিফিলো

রিচার্জ API ডেভেলপার ডকুমেন্টেশন

মেথড: শুধুমাত্র POST রিকোয়েস্ট গ্রহণ করা হয়।

অথেনটিকেশন: API Key এবং Secret Key বাধ্যতামূলক।

নিরাপত্তা: Allowed Domain খালি থাকলে API call ব্লক হবে।

ভেরিফিকেশন: Business/Company Profile অবশ্যই approved হতে হবে।

রেসপন্স: প্রতিটি response-এ success, code, message থাকবে।

API এন্ডপয়েন্ট

নিচের এন্ডপয়েন্টে POST রিকোয়েস্ট পাঠিয়ে রিচার্জ সম্পন্ন করতে হবে।

POST

https://refillo.top/api/recharge

রিকোয়েস্ট পাঠানোর সময় form-data অথবা x-www-form-urlencoded ব্যবহার করতে পারবেন।

রিকোয়েস্ট প্যারামিটার

রিচার্জ অনুরোধ পাঠানোর জন্য নিচের তথ্যগুলো সঠিকভাবে প্রদান করতে হবে।

ফিল্ড	আবশ্যক	বর্ণনা	উদাহরণ
api_key	হ্যাঁ	আপনার API Key	rk_xxxxxxxxxxxxx
secret_key	হ্যাঁ	আপনার Secret Key	sk_xxxxxxxxxxxxx
operator	হ্যাঁ	অপারেটর কোড	GP
mobile	হ্যাঁ	গ্রাহকের মোবাইল নম্বর	017XXXXXXXX
amount	হ্যাঁ	রিচার্জের পরিমাণ	100
account_type	হ্যাঁ	`prepaid` অথবা `postpaid`	prepaid
domain	পরিস্থিতিভেদে	Allowed Domain verify করার জন্য পাঠানো যেতে পারে	example.com

API ব্যবহারের শর্তাবলি

রিচার্জ API call সফলভাবে প্রসেস হওয়ার আগে নিচের শর্তগুলো যাচাই করা হবে।

১. API Key এবং Secret Key সঠিক হতে হবে

ভুল API Key বা Secret Key হলে request সঙ্গে সঙ্গে reject করা হবে।

২. API status অবশ্যই active হতে হবে

inactive বা suspended API দিয়ে call করা যাবে না।

৩. Allowed Domain বাধ্যতামূলক

API credential-এ allowed_domain খালি থাকলে API call block হবে। Allowed Domain সেট করা থাকলে request সেই domain থেকে আসতে হবে।

৪. Allowed IP সেট করা থাকলে IP match হতে হবে

Allowed IP দেওয়া থাকলে অন্য IP থেকে request গেলে reject করা হবে।

৫. Personal account থেকে API ব্যবহার করা যাবে না

শুধুমাত্র business অথবা company account API ব্যবহার করতে পারবে।

৬. User account status active হতে হবে

pending, banned, suspended account থেকে API call করা যাবে না।

৭. বিজনেস বা কোম্পানি ভেরিফিকেশন অনুমোদিত হতে হবে

বিজনেস অথবা কোম্পানি অ্যাকাউন্ট থেকে API ব্যবহার করতে হলে সংশ্লিষ্ট ভেরিফিকেশন তথ্য ড্যাশবোর্ডে জমা দিয়ে অনুমোদিত থাকতে হবে।

৮. ব্যালেন্স পর্যাপ্ত থাকতে হবে

ব্যালেন্স কম থাকলে recharge শুরুই হবে না।

৯. Recharge failed হলে amount refund হবে

Provider side failed হলে কাটা amount ফেরত দেওয়া হবে।

১০. Recharge success হলে commission যোগ হবে

সফল recharge হলে configured commission অনুযায়ী balance-এ কমিশন যোগ হবে।

অপারেটর কোড

রিকোয়েস্ট পাঠানোর সময় নিচের অপারেটর কোডগুলোর যেকোনো একটি ব্যবহার করুন।

কোড	অপারেটরের নাম
GP	গ্রামীণফোন
GPST	স্কিটো (গ্রামীণফোন)
BL	বাংলালিংক
RB	রবি
AT	এয়ারটেল
TT	টেলিটক

PHP cURL উদাহরণ

PHP ব্যবহার করে কীভাবে API call করবেন তার নমুনা নিচে দেওয়া হলো।

PHP উদাহরণ

<?php

$data = [
    "api_key"      => "YOUR_API_KEY",
    "secret_key"   => "YOUR_SECRET_KEY",
    "operator"     => "GP",
    "mobile"       => "017XXXXXXXX",
    "amount"       => 100,
    "account_type" => "prepaid",
    "domain"       => "example.com"
];

$ch = curl_init("https://refillo.top/api/recharge");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Accept: application/json",
    "X-Client-Domain: example.com"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

cURL কমান্ড উদাহরণ

সার্ভার বা টার্মিনাল থেকে cURL দিয়েও একই request পাঠানো যাবে।

cURL উদাহরণ

curl -X POST "https://refillo.top/api/recharge" \
-H "Accept: application/json" \
-H "X-Client-Domain: example.com" \
-d "api_key=YOUR_API_KEY" \
-d "secret_key=YOUR_SECRET_KEY" \
-d "operator=GP" \
-d "mobile=017XXXXXXXX" \
-d "amount=100" \
-d "account_type=prepaid" \
-d "domain=example.com"

সফল রেসপন্স

রিচার্জ সফল হলে নিচের মতো JSON response পাওয়া যাবে।

সফল JSON

{
  "success": true,
  "code": 1700,
  "message": "রিচার্জ সফল হয়েছে।",
  "mobile": "017XXXXXXXX",
  "operator": "Grameenphone",
  "account_type": "prepaid",
  "amount": "100.00",
  "commission": "2.00",
  "recharge_before_balance": "1000.00",
  "recharge_after_balance": "902.00",
  "user_balance": "902.00",
  "order_number": "RCG202604101234567890",
  "operator_transaction_id": "BDSP987654"
}

নোট: সফল recharge হলে amount deduct হবে এবং configured commission balance-এ যোগ হবে।

এরর কোড তালিকা

প্রতিটি failure response-এ একটি নির্দিষ্ট code থাকবে, যাতে সমস্যা দ্রুত বোঝা যায়।

Code	অর্থ
1001	Validation error
1002	অপারেটর সমর্থিত নয়
1003	মোবাইল নম্বর সঠিক নয়
1101	অবৈধ API Key অথবা Secret Key
1102	অবৈধ API configuration
1103	API inactive
1104	API suspended
1105	API ব্যবহারযোগ্য নয়
1201	Allowed domain পাওয়া যায়নি
1202	Domain not allowed
1203	IP not allowed
1301	Service provider unavailable
1401	ব্যবহারকারী পাওয়া যায়নি
1402	অবৈধ ব্যবহারকারী
1403	Personal account not allowed
1404	Only business/company account allowed
1405	User account pending
1406	User account banned
1407	User account suspended
1408	User account not active
1501	Business profile submitted হয়নি
1502	Business profile approved নয়
1503	Company profile submitted হয়নি
1504	Company profile approved নয়
1601	পর্যাপ্ত ব্যালেন্স নেই
1700	Recharge success
1701	Recharge failed, টাকা refund করা হয়েছে
1901	Unexpected server error

ত্রুটি রেসপন্স উদাহরণ

নিচে বিভিন্ন ধরনের error response-এর নমুনা দেওয়া হলো।

১. অবৈধ API Key অথবা Secret Key

API error

{
  "success": false,
  "code": 1101,
  "message": "অবৈধ API Key অথবা Secret Key।"
}

২. Allowed Domain পাওয়া যায়নি

Domain missing

{
  "success": false,
  "code": 1201,
  "message": "Allowed domain পাওয়া যায়নি। অনুগ্রহপূর্বক API সেটিংস আপডেট করুন।"
}

৩. অনুমোদিত নয় এমন Domain

Domain not allowed

{
  "success": false,
  "code": 1202,
  "message": "এই Domain থেকে API call করার অনুমতি নেই।"
}

৪. অনুমোদিত নয় এমন IP

IP not allowed

{
  "success": false,
  "code": 1203,
  "message": "এই IP থেকে API call করার অনুমতি নেই।"
}

৫. Personal account blocked

Personal blocked

{
  "success": false,
  "code": 1403,
  "message": "পার্সোনাল অ্যাকাউন্ট থেকে API ব্যবহার করা যাবে না। শুধুমাত্র বিজনেস অথবা কোম্পানি অ্যাকাউন্ট API ব্যবহার করতে পারবে।"
}

৬. Profile approved নয়

Profile not approved

{
  "success": false,
  "code": 1502,
  "message": "আপনার বিজনেস প্রোফাইল এখনো অনুমোদিত হয়নি। ড্যাশবোর্ড থেকে অ্যাকাউন্ট ভেরিফিকেশনের অবস্থা দেখুন।"
}

৭. পর্যাপ্ত ব্যালেন্স নেই

Balance error

{
  "success": false,
  "code": 1601,
  "message": "পর্যাপ্ত ব্যালেন্স নেই।",
  "user_balance": "50.00"
}

৮. Recharge failed, টাকা refund

Recharge failed

{
  "success": false,
  "code": 1701,
  "message": "সার্ভিস সাময়িকভাবে অনুপলব্ধ। রিচার্জ সম্পন্ন হয়নি, অর্থ ফেরত দেওয়া হয়েছে।",
  "order_number": "RCG202604101234567890",
  "user_balance": "1000.00"
}

৯. Validation error

Validation error

{
  "success": false,
  "code": 1001,
  "message": "প্রয়োজনীয় তথ্য সঠিকভাবে প্রদান করা হয়নি।",
  "errors": {
    "mobile": [
      "The mobile field is required."
    ]
  }
}

গুরুত্বপূর্ণ: Recharge request received হওয়ার পর প্রথমে balance deduct হতে পারে। Provider success না দিলে recharge failed ধরা হবে এবং amount refund করা হবে। Successful recharge হলে commission balance-এ যোগ হবে।