ডেভেলপার

API রেফারেন্স

ইনভয়েস, পেমেন্ট লিংক, ব্যালেন্স ও গ্রহণযোগ্য কয়েনের জন্য একটি ছোট REST API। এটি HTTPS-এর মাধ্যমে JSON ব্যবহার করে, এবং প্রতিটি রিকোয়েস্ট আপনার সিক্রেট কি দিয়ে করা হয়।

বেস URL

প্রোডাকশন: https://cryptomerchant.online/api/v1
লোকাল ডেভেলপমেন্ট: http://localhost:3000/api/v1

এই API-এর মেশিনে পড়ার উপযোগী বিবরণ আছে /openapi.json-এ (OpenAPI 3.1)। আপনি এটি Postman বা কোনো ক্লায়েন্ট জেনারেটরে ইমপোর্ট করতে পারেন।

অথেন্টিকেশন

প্রতিটি রিকোয়েস্টের Authorization হেডারে আপনার সিক্রেট কি Bearer টোকেন হিসেবে পাঠান। পোর্টালে ডেভেলপার অংশে কি তৈরি করুন।

HTTP

Authorization: Bearer cm_live_…

মেইননেটে কি শুরু হয় cm_live_ দিয়ে এবং টেস্টনেটে cm_test_ দিয়ে।
পুরো কি শুধু একবার, তৈরি করার সময় দেখানো হয়। আমরা শুধু এর একটি হ্যাশ সংরক্ষণ করি, তাই এটি কোথাও নিরাপদে রাখুন।
কি শুধু আপনার সার্ভারে ব্যবহার করুন। কখনো ওয়েব পেজ, মোবাইল অ্যাপ বা পাবলিক কোড রিপোজিটরিতে রাখবেন না।
কোনো কি ফাঁস হয়ে থাকতে পারে মনে হলে, পোর্টালে সেটি বাতিল করে নতুন একটি তৈরি করুন।

এরর

কোনো রিকোয়েস্ট ব্যর্থ হলে, রেসপন্সে একটি HTTP এরর স্ট্যাটাস এবং একটি JSON বডি থাকে, যাতে মেশিনে পড়ার উপযোগী একটি code এবং মানুষের পড়ার উপযোগী একটি message থাকে:

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTP স্ট্যাটাস

400: রিকোয়েস্টটি সঠিক নয়, যেমন কোনো ফিল্ড নেই বা পরিমাণ খুব কম।
401: API কি নেই, ভুল, বা বাতিল করা হয়েছে।
403: আপনার অ্যাকাউন্ট এটি করতে পারে না: এটি এখনও লাইভ নয়, অথবা স্থগিত।
404: অবজেক্টটি নেই, অথবা এটি অন্য কোনো ব্যবসার।
409: ইনভয়েসটি তার বর্তমান স্ট্যাটাসে এটি করতে পারে না, যেমন এমন ইনভয়েস বাতিল করা যাতে আগেই পেমেন্ট এসেছে।
500: আমাদের দিকে কোনো সমস্যা হয়েছে। একটু পরে আবার চেষ্টা করুন।

যে কোডগুলো দেখতে পারেন

invalid_json: রিকোয়েস্ট বডি কোনো JSON অবজেক্ট নয়।
invalid_request: কোনো ফিল্ড নেই বা সঠিক নয়। মেসেজে ফিল্ডটির নাম থাকে।
unauthorized: API কি নেই, ভুল, বা বাতিল করা হয়েছে।
account_suspended: এই মার্চেন্ট অ্যাকাউন্টটি স্থগিত।
merchant_not_live: আপনার অ্যাকাউন্ট এখনও লাইভ নয়। আগে পোর্টালে সেটআপ শেষ করুন।
invalid_amount: পরিমাণ নেই, সংখ্যা নয়, অথবা শূন্যের চেয়ে বেশি নয়।
amount_too_small: পরিমাণটির মূল্য 0.50 মার্কিন ডলারের কম।
invalid_asset: কয়েন আইডিটি কোনো পরিচিত কয়েনের নয়।
asset_not_accepted: আপনি এই কয়েন গ্রহণ করেন না।
invalid_state: ইনভয়েসটি তার বর্তমান স্ট্যাটাসে এটি করতে পারে না।
not_found: এই আইডির কোনো অবজেক্ট নেই।
server_error: আমাদের দিকে কোনো সমস্যা হয়েছে।

ইনভয়েস অবজেক্ট

API রেসপন্স ও ওয়েবহুকে ইনভয়েসের গঠন এমন। পরিমাণগুলো দশমিক স্ট্রিং, তাই কোনো নির্ভুলতা হারায় না।

idstring: ইনভয়েস আইডি, inv_ দিয়ে শুরু।
objectstring: সবসময় invoice।
statusstring: বর্তমান স্ট্যাটাস। নিচে স্ট্যাটাসের তালিকা দেখুন।
amountstring: আপনার চাওয়া দাম, currency-তে।
currencystring: দামের মুদ্রা, যেমন USD।
amount_usdstring: মার্কিন ডলারে দাম।
descriptionstring | null: আপনার বিবরণ, যা গ্রাহককে দেখানো হয়।
order_idstring | null: আপনার নিজস্ব অর্ডার রেফারেন্স।
customer_emailstring | null: গ্রাহকের ইমেইল, যদি আপনি দিয়ে থাকেন।
metadataobject: ইনভয়েস তৈরির সময় আপনি যে অবজেক্ট দিয়েছিলেন, অপরিবর্তিত অবস্থায় ফেরত দেওয়া হয়।
coinobject | null: গ্রাহকের বেছে নেওয়া কয়েন, অথবা তিনি আসলে যে কয়েনে পেমেন্ট করেছেন, এর id, symbol ও networkসহ। কয়েন বেছে নেওয়া না হওয়া পর্যন্ত null।
requested_coinobject | null: সাধারণত null। গ্রাহক অন্য কয়েনে বা অন্য নেটওয়ার্কে পেমেন্ট করলে এবং পেমেন্টটি গণ্য হলে, এটি হলো ইনভয়েসে চাওয়া কয়েন, coin-এর মতো একই ফিল্ডসহ। দেখুন ভুল কয়েন বা ভুল নেটওয়ার্ক।
pay_addressstring | null: এই ইনভয়েসের ডিপোজিট ঠিকানা। কয়েন বেছে নেওয়া না হওয়া পর্যন্ত null।
pay_amountstring | null: বেছে নেওয়া কয়েনে পাঠানোর সঠিক পরিমাণ।
network_fee_amountstring: pay_amount-এর অংশ: দামের ওপরে গ্রাহক যে গ্যাস ফি দেন, কয়েনে। না থাকলে 0।
network_fee_usdstring: একই গ্যাস ফি, মার্কিন ডলারে।
rate_usdstring | null: বেছে নেওয়া কয়েনের এক ইউনিটের লক করা দাম, মার্কিন ডলারে।
received_amountstring: এখন পর্যন্ত কত এসেছে, বেছে নেওয়া কয়েনে।
received_usdstring: যা এসেছে তার মার্কিন ডলার মূল্য।
overpaid_amountstring: ইনভয়েসে চাওয়া পরিমাণের চেয়ে কত বেশি পেমেন্ট হয়েছে, বেছে নেওয়া কয়েনে।
refunded_amountstring: রিফান্ড লিংক দিয়ে এই পেমেন্টে আপনি কত রিফান্ড করেছেন, পেমেন্ট করা কয়েনে। কিছু না হলে 0।
checkout_urlstring: ইনভয়েস পেজ। পেমেন্টের জন্য গ্রাহককে এখানে পাঠান।
redirect_urlstring | null: পেমেন্টের পর গ্রাহক কোথায় যেতে পারেন।
expires_atISO 8601: কোনো পেমেন্ট দেখা না গেলে ইনভয়েসের মেয়াদ কখন শেষ হবে।
paid_atISO 8601 | null: ইনভয়েস কখন পরিশোধিত হয়েছে, অথবা null।
created_atISO 8601: ইনভয়েস কখন তৈরি হয়েছে।

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

ইনভয়েস স্ট্যাটাস

openখোলা: তৈরি হয়েছে। গ্রাহক এখনও কোনো কয়েন বেছে নেননি।
awaiting_paymentপেমেন্টের অপেক্ষায়: একটি কয়েন বেছে নেওয়া হয়েছে, ডিপোজিট ঠিকানা বরাদ্দ হয়েছে এবং রেট লক হয়েছে।
confirmingকনফার্ম হচ্ছে: অন-চেইনে একটি পেমেন্ট দেখা গেছে এবং সেটি কনফার্মেশনের অপেক্ষায় আছে।
underpaidকম পেমেন্ট: কনফার্ম হওয়া পেমেন্টে ঘাটতি আপনার ছাড়ের সীমার চেয়ে বেশি। গ্রাহক বাকিটা পেমেন্ট করতে বা রিফান্ড চাইতে পারেন।
paidপরিশোধিত: পরিশোধিত ও কনফার্ম হয়েছে। ফি বাদে পরিমাণটি আপনার ব্যালেন্সে আছে। আংশিক রিফান্ডের পরও এই স্ট্যাটাস থাকে।
expiredমেয়াদোত্তীর্ণ: কোনো পেমেন্ট দেখা যাওয়ার আগেই সময় শেষ হয়েছে।
cancelledবাতিল: কোনো পেমেন্ট দেখা যাওয়ার আগেই ইনভয়েসটি বাতিল করা হয়েছে।
refundedরিফান্ড হয়েছে: কম পেমেন্টের ইনভয়েসে গ্রাহক যা পাঠিয়েছিলেন তা রিফান্ড করা হয়েছে, অথবা একটি পরিশোধিত ইনভয়েস থেকে আপনি যা রেখেছিলেন তার পুরোটা রিফান্ড করেছেন।

একটি ইনভয়েস তৈরি করুন

POST/invoices

একটি ইনভয়েস তৈরি করে এবং 201 স্ট্যাটাসসহ ইনভয়েস অবজেক্ট ফেরত দেয়। গ্রাহককে এর checkout_url-এ পাঠান।

বডি প্যারামিটার

amountআবশ্যকnumber | string: দাম, সংখ্যা বা দশমিক স্ট্রিং হিসেবে। মূল্য অন্তত 0.50 মার্কিন ডলার হতে হবে।
currencyঐচ্ছিকstring: দামের মুদ্রা, যেমন USD। ডিফল্ট USD।
descriptionঐচ্ছিকstring: গ্রাহক কীসের জন্য পেমেন্ট করছেন, সর্বোচ্চ 300 অক্ষর। ইনভয়েস পেজে দেখানো হয়।
order_idঐচ্ছিকstring: ইনভয়েসকে কোনো অর্ডারের সাথে মেলাতে আপনার নিজস্ব অর্ডার রেফারেন্স, সর্বোচ্চ 120 অক্ষর।
customer_emailঐচ্ছিকstring: গ্রাহকের ইমেইল ঠিকানা। পোর্টালে পেমেন্টগুলো গ্রাহক অনুযায়ী সাজানো থাকে।
customer_nameঐচ্ছিকstring: গ্রাহকের নাম, সর্বোচ্চ 120 অক্ষর।
redirect_urlঐচ্ছিকstring: একটি পূর্ণ URL, যেখানে পেমেন্টের পর গ্রাহক যেতে পারেন।
metadataঐচ্ছিকobject: 4 KB পর্যন্ত যেকোনো JSON অবজেক্ট। ইনভয়েসে ও ওয়েবহুকে অপরিবর্তিত অবস্থায় ফেরত দেওয়া হয়।
coinঐচ্ছিকstring: আইডি দিয়ে একটি কয়েন আগে থেকে বেছে দিন, যেমন USDT.TRON। এটি অবশ্যই আপনার গ্রহণযোগ্য কয়েনগুলোর একটি হতে হবে।

আগে থেকে বেছে দেওয়া coin থাকলে, ডিপোজিট ঠিকানা সঙ্গে সঙ্গে বরাদ্দ হয় ও রেট লক হয়, তাই pay_address ও pay_amount পূরণ করা থাকে এবং আপনি নিজের ইন্টারফেসে পেমেন্টের বিবরণ দেখাতে পারেন।

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

ইনভয়েসের তালিকা

GET/invoices

আপনার ইনভয়েসগুলো ফেরত দেয়, নতুনগুলো আগে, একবারে এক পেজ করে।

কোয়েরি প্যারামিটার

statusঐচ্ছিকstring: শুধু এই স্ট্যাটাসের ইনভয়েস, যেমন paid। ওপরের স্ট্যাটাসগুলোর একটি হতে হবে।
limitঐচ্ছিকnumber: কতগুলো ইনভয়েস ফেরত দেবে, 1 থেকে 100। ডিফল্ট 20।
starting_afterঐচ্ছিকstring: একটি ইনভয়েস আইডি। পরের পেজের জন্য, এর পরে আসা ইনভয়েসগুলো ফেরত দেয়।

ইনভয়েসগুলো থাকে data-তে। has_more যখন true, তখন পরের পেজ চাইতে starting_after-এ আপনার পাওয়া শেষ ইনভয়েসের আইডি দিন।

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

রেসপন্স

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

একটি ইনভয়েস আনুন

GET/invoices/{id}

আইডি দিয়ে একটি ইনভয়েস ফেরত দেয়।

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

একটি ইনভয়েস বাতিল করুন

POST/invoices/{id}/cancel

একটি ইনভয়েস বাতিল করে। এটি শুধু তখনই কাজ করে যখন ইনভয়েসটি অপরিশোধিত এবং এর জন্য কোনো পেমেন্ট দেখা যায়নি।

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

ব্যালেন্স

GET/balances

আপনার ব্যবসার কাছে প্রতিটি কয়েনে কত আছে, মার্কিন ডলারে মোট পরিমাণ, এবং আপনার গ্যাস ব্যালেন্স ফেরত দেয়।

data[].coin: কয়েন আইডি, যেমন USDT.TRON।
data[].symbol: কয়েনের সিম্বল, যেমন USDT।
data[].network: কয়েনটি যে নেটওয়ার্কে আছে।
data[].amount: আপনার কাছে কয়েনটি কত আছে, দশমিক স্ট্রিং হিসেবে।
data[].usd: বর্তমান দামে এর মার্কিন ডলার মূল্য।
total_usd: আপনার সব কয়েনের মার্কিন ডলার মূল্য।
gas_balance_usd: মার্কিন ডলারে আপনার গ্যাস ব্যালেন্স, যা গ্যাস ফি দিতে ব্যবহার হয়।

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

রেসপন্স

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

গ্রহণযোগ্য কয়েন

GET/coins

আপনি এখন যে কয়েনগুলো গ্রহণ করেন তা ফেরত দেয়, প্রতিটির id, symbol, name, network ও decimalsসহ। ইনভয়েস তৈরির সময় id-কে coin হিসেবে ব্যবহার করুন। উদাহরণ:

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

রেসপন্স

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

একটি পেমেন্ট লিংক তৈরি করুন

POST/payment-links

একটি পেমেন্ট লিংক তৈরি করে এবং 201 স্ট্যাটাসসহ সেটি ফেরত দেয়, এর id ও শেয়ারযোগ্য urlসহ।

বডি প্যারামিটার

titleআবশ্যকstring: গ্রাহক যার জন্য পেমেন্ট করেন তার নাম, সর্বোচ্চ 120 অক্ষর।
amountঐচ্ছিকnumber | string: একটি নির্দিষ্ট দাম। গ্রাহককে পরিমাণ লিখতে দিতে এটি বাদ দিন।
currencyঐচ্ছিকstring: দামের মুদ্রা। ডিফল্ট USD।
descriptionঐচ্ছিকstring: গ্রাহককে দেখানো আরও বিস্তারিত, সর্বোচ্চ 300 অক্ষর।

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

রেসপন্স

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

পেমেন্ট লিংকের তালিকা

GET/payment-links

আপনার সবচেয়ে সাম্প্রতিক 100টি পেমেন্ট লিংক ফেরত দেয়, নতুনগুলো আগে, data-তে।

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

পেআউট ওয়েবহুক (payout.sent ও payout.failed) data-তে এই অবজেক্টটি বহন করে। রেভিনিউ স্প্লিট থেকে কোনো পার্টনারের অংশের পেআউটও একই অবজেক্ট ব্যবহার করে, যেখানে partner_share true হিসেবে সেট থাকে।

idstring: পেআউট আইডি।
objectstring: সবসময় payout।
coinstring: কয়েন আইডি, যেমন USDT.TRON।
amountstring: পেআউট করা পরিমাণ, সেই কয়েনে।
network_feestring: এটি পাঠানোর গ্যাস ফি, সেই কয়েনে।
to_addressstring: যে ওয়ালেট ঠিকানায় এটি পাঠানো হয়েছে।
statusstring: queued, running, done বা failed।
tx_hashstring | null: ব্লকচেইনে ট্রানজ্যাকশন আইডি, পাঠানো হয়ে গেলে।
autoboolean: পেআউটটি কোনো ব্যক্তির অনুরোধে নয়, স্বয়ংক্রিয়ভাবে করা হলে true।
partner_shareboolean: এই পেআউটটি রেভিনিউ স্প্লিট থেকে কোনো পার্টনারের অংশ হলে, যা পার্টনারের ওয়ালেটে পাঠানো হয়েছে, true।
created_atISO 8601: পেআউটটি কখন তৈরি হয়েছে।

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

এরপর ওয়েবহুক সেট আপ করুন, যাতে পেমেন্ট হওয়ার সঙ্গে সঙ্গে আপনার সার্ভার খবর পায়।