ڈیولپرز

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: کوائن ID کسی معلوم کوائن کی نہیں۔
asset_not_accepted: آپ یہ کوائن قبول نہیں کرتے۔
invalid_state: انوائس اپنے موجودہ اسٹیٹس میں یہ کام نہیں کر سکتی۔
not_found: اس ID کا کوئی آبجیکٹ موجود نہیں۔
server_error: ہماری طرف کچھ غلط ہو گیا۔

انوائس آبجیکٹ

API جوابات اور webhooks میں انوائسز کی یہی شکل ہوتی ہے۔ رقمیں ڈیسیمل اسٹرنگز کی صورت میں ہوتی ہیں، اس لیے درستگی ضائع نہیں ہوتی۔

idstring: انوائس ID، جو 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 آبجیکٹ۔ انوائس پر اور webhooks میں بغیر تبدیلی کے واپس آتا ہے۔
coinاختیاریstring: کوائن کو اس کی ID سے پہلے سے منتخب کریں، مثلاً 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: ایک انوائس ID۔ اگلے پیج کے لیے اس کے بعد آنے والی انوائسز واپس کرتا ہے۔

انوائسز data میں ہوتی ہیں۔ جب has_more کی ویلیو true ہو تو اگلا پیج مانگیں، اور starting_after میں آخری موصول شدہ انوائس کی ID دیں۔

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}

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: کوائن ID، مثلاً 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"

پے آؤٹ webhooks (payout.sent اور payout.failed) یہ آبجیکٹ data میں لاتے ہیں۔ آمدنی کی تقسیم سے کسی پارٹنر کے حصے کے پے آؤٹس بھی یہی آبجیکٹ استعمال کرتے ہیں، جس میں partner_share کی قدر true ہوتی ہے۔

idstring: پے آؤٹ ID۔
objectstring: ہمیشہ payout۔
coinstring: کوائن ID، مثلاً USDT.TRON۔
amountstring: پے آؤٹ کی گئی رقم، اسی کوائن میں۔
network_feestring: اسے بھیجنے کی گیس فیس، اسی کوائن میں۔
to_addressstring: وہ والٹ ایڈریس جس پر یہ بھیجا گیا۔
statusstring: queued، running، done یا failed۔
tx_hashstring | null: بلاک چین پر ٹرانزیکشن ID، بھیجے جانے کے بعد۔
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"
}

اس کے بعد webhooks سیٹ اپ کریں تاکہ ادائیگیاں ہوتے ہی آپ کے سرور کو اطلاع مل جائے۔