DPT Learn — ایکوائرنگ

USDC چیک آؤٹ انٹیگریشن

چیک آؤٹ پر USDC ادائیگیوں کی انٹیگریشن کے لیے ایک حقیقت پسندانہ انجینئرنگ گائیڈ: API پیٹرنز، نیٹ ورک کا انتخاب، ویب ہُک کی آئیڈیمپوٹینسی، اور وہ ناکامیاں جن کا آپ کو پروڈکشن میں سامنا ہوگا۔

خلاصہ

USDC چیک آؤٹ انٹیگریشن ایک جانے پہچانے پیٹرن پر چلتی ہے: اپنے سرور پر ایک پیمنٹ انٹینٹ بنائیں (رقم، کرنسی، نیٹ ورک کی ترجیحات)، اپنے ایکوائرر سے ہوسٹڈ چیک آؤٹ URL یا ویجیٹ کنفیگریشن حاصل کریں، خریدار کو اپنے والیٹ میں ادائیگی کرنے دیں، اور تصدیقی ویب ہُک کو آئیڈیمپوٹنٹ طریقے سے سنبھالیں۔ سب سے اہم انجینئرنگ فیصلے یہ ہیں: نیٹ ورک کا انتخاب (ایک سینٹ سے کم فیس کے لیے Solana یا Base کو ڈیفالٹ رکھیں)، ویب ہُک کی آئیڈیمپوٹینسی (آرڈر ID + tx ہیش استعمال کریں)، ریفنڈ کا طریقۂ کار (چیک آؤٹ پر والیٹ ایڈریس جمع کریں، ریفنڈ API فراہم کریں)، اور والیٹ پر دستخط کے مرحلے کے لیے ہموار UX (موبائل والیٹس کے لیے ڈیپ لنک، ڈیسک ٹاپ کے لیے QR بطور متبادل)۔ درست طریقے سے کیا جائے تو USDC چیک آؤٹ شروع سے آخر تک 30 سیکنڈ سے کم میں مکمل ہوتا ہے اور ایکوائرر کے لحاظ سے مرچنٹ کو 0.3%–1% لاگت آتی ہے۔

API کی معیاری ساخت

USDC ایکوائرنگ APIs عموماً اسی پیمنٹ انٹینٹ پیٹرن کی پیروی کرتی ہیں جسے Stripe نے مقبول بنایا۔ کم از کم درکار حصے:

  1. سرور پیمنٹ انٹینٹ بناتا ہے

    POST /v1/payments ایسی باڈی کے ساتھ جس میں amount، currency (فیاٹ میں قیمت بتانے پر USD؛ اسٹیبل کوائن میں قیمت بتانے پر USDC)، settlement_preference (USDC بمقابلہ فیاٹ)، networks (اجازت یافتہ فہرست)، order_id (آپ کی آئیڈیمپوٹینسی کی)، success_url، cancel_url، اور آپ کے اپنے حسابات کی مطابقت کے لیے ایک metadata بلاب شامل ہو۔

  2. ایکوائرر چیک آؤٹ URL یا ویجیٹ کنفیگریشن واپس بھیجتا ہے

    ہوسٹڈ چیک آؤٹ کے لیے: ایک URL جس پر خریدار کو ری ڈائریکٹ کیا جاتا ہے۔ ایمبیڈڈ ویجیٹ کے لیے: ایک کلائنٹ سائیڈ کنفیگریشن (پبلشیبل کی، انٹینٹ ID) جسے ویجیٹ لوڈ کرتا ہے۔ دونوں طریقے والیٹ کی شناخت، نیٹ ورک کے انتخاب اور کوٹ کی نمائش کو سنبھالتے ہیں۔

  3. خریدار والیٹ میں دستخط کرتا ہے، آن چین ٹرانسفر نشر ہوتا ہے

    موبائل: MetaMask، Phantom، Trust وغیرہ میں ڈیپ لنک۔ ڈیسک ٹاپ: WalletConnect QR یا براؤزر ایکسٹینشن پاپ اپ۔ خریدار رقم کا جائزہ لیتا ہے اور دستخط کرتا ہے۔

  4. ایکوائرر تصدیقات کا انتظار کرتا ہے، ویب ہُک بھیجتا ہے

    POST your_webhook_url ایسے پے لوڈ کے ساتھ جس میں event_type: “payment.succeeded”، order_id، amount، tx_hash، network، اور ایک دستخط شامل ہو جس کی تصدیق آپ ایکوائرر کے ویب ہُک سیکرٹ سے کرتے ہیں۔

  5. سرور آئیڈیمپوٹنٹ طریقے سے آرڈر کو ادا شدہ نشان زد کرتا ہے

    ویب ہُک کے دستخط کی تصدیق کریں، اپنے DB میں (order_id, tx_hash) تلاش کریں، اگر پہلے سے نشان زد نہیں تو ادا شدہ نشان زد کریں، اور آرڈر کی تکمیل (fulfillment) شروع کریں۔

نیٹ ورک کا انتخاب

کون سے نیٹ ورکس قبول کیے جائیں، یہ UX اور لاگت کے درمیان توازن کا فیصلہ ہے:

  • Solana: ایک سینٹ سے کم نیٹ ورک فیس، ایک سیکنڈ سے کم میں تصدیق۔ کم اوسط آرڈر ویلیو (AOV) کے لیے بہترین ڈیفالٹ۔
  • Base: چند سینٹ نیٹ ورک فیس، چند سیکنڈ میں تصدیق۔ والیٹس کی مضبوط سپورٹ؛ کرپٹو سے واقف صارفین کے لیے اچھا ڈیفالٹ۔
  • Polygon، Arbitrum: فیس اور رفتار Base جیسی۔ شامل کرنا ٹھیک ہے لیکن لازمی نہیں۔
  • Ethereum mainnet: گیس کے لحاظ سے $1–$8+ نیٹ ورک فیس۔ چھوٹے آرڈرز پر خریداروں کے لیے تکلیف دہ۔ زیادہ AOV (>$500) کے لیے یا متبادل کے طور پر قبول کریں۔
  • Tron: اگر آپ ایشیا/افریقہ کے USDT بہاؤ کو ہدف بنا رہے ہیں تو USDC کے ساتھ USDT-TRON کی سپورٹ پر غور کرنا مفید ہے۔

ویب ہُک کی آئیڈیمپوٹینسی

ویب ہُکس دوبارہ کوشش کرتے ہیں۔ آپ کا ہینڈلر آئیڈیمپوٹنٹ ہونا چاہیے، یعنی ایک ہی ایونٹ دوبارہ آنے پر نتیجہ نہ بدلے۔ معیاری پیٹرن:

  1. اپنے ایکوائرر کے سیکرٹ کے ساتھ HMAC-SHA256 استعمال کر کے ویب ہُک کے دستخط کی تصدیق کریں۔
  2. پے لوڈ سے (order_id, tx_hash) نکالیں۔
  3. یہ جوڑا اپنے processed_payments ٹیبل میں تلاش کریں۔
  4. اگر مل جائے: مزید کچھ کیے بغیر 200 OK واپس کریں۔
  5. اگر نہ ملے: قطار شامل کریں (جوڑے پر UNIQUE پابندی کے ساتھ)، پھر اپنے مرکزی آرڈر ٹیبل میں آرڈر کو ادا شدہ نشان زد کریں، پھر تکمیل شروع کریں۔
  6. مرحلہ 5 کو ایک ہی DB ٹرانزیکشن میں رکھیں تاکہ عمل کے درمیان کریش ہونے سے دوہری تکمیل نہ ہو۔

زیادہ تر ایکوائرنگ ویب ہُکس میں ایک ڈیلیوری ID شامل ہوتی ہے، اسے ڈی بگنگ کے لیے لاگ کریں، لیکن اسے آئیڈیمپوٹینسی کی کے طور پر استعمال نہ کریں۔ نیٹ ورک کی تصدیقات اور ایکوائرر کی دوبارہ کوششیں مختلف ڈیلیوری IDs لیکن ایک ہی tx_hash کے ساتھ دوہرے payment.succeeded ایونٹس پیدا کر سکتی ہیں؛ آپ کی ڈپلیکیٹ کی جانچ آن چین شناخت پر ہونی چاہیے، ڈیلیوری پر نہیں۔

ریفنڈ کا طریقۂ کار

دو پیٹرنز غالب ہیں:

  • بھیجنے والے کو ریفنڈ (Refund-to-sender): ایکوائرر USDC اسی ایڈریس پر واپس بھیجتا ہے جس سے خریدار نے اصل ادائیگی کی تھی۔ سب سے صاف UX؛ یہ اس لیے کام کرتا ہے کہ آن چین ادائیگی کے ریکارڈ میں سورس ایڈریس موجود ہوتا ہے۔
  • مخصوص ایڈریس پر ریفنڈ (Refund-to-specified-address): خریدار ریفنڈ کی منزل بتاتا ہے (اگر اس نے کسی ایکسچینج یا ہاٹ والیٹ سے ادائیگی کی ہو تو یہ سورس سے مختلف ہو سکتی ہے)۔ زیادہ تر ایکوائررز یہ سہولت destination_address کے ساتھ POST /v1/refunds کے ذریعے فراہم کرتے ہیں۔

ریفنڈ کے مرحلے پر نیٹ ورک فیس مرچنٹ ادا کرتا ہے۔ مکمل اور جزوی دونوں ریفنڈ سپورٹ ہوتے ہیں۔ ریفنڈ میں بھی آن چین تصدیق کا اتنا ہی وقت لگتا ہے جتنا اصل ادائیگی میں۔

پروڈکشن میں ناکامی کی صورتیں

  • خریدار دستخط کے بعد چھوڑ دیتا ہے۔ آن چین ٹرانسفر نشر ہو چکا ہوتا ہے لیکن ویب ہُک بھیجے جانے سے پہلے خریدار ٹیب بند کر دیتا ہے۔ ایکوائرر پھر بھی آن چین نگرانی کے ذریعے ادائیگی کا پتہ لگا کر اس کی تصدیق کرتا ہے؛ آپ کی تکمیل ویب ہُک سے چلتی ہے، ری ڈائریکٹ سے نہیں۔
  • خریدار غلط رقم ادا کرتا ہے۔ زیادہ تر ایکوائررز آن چین شناخت کے وقت غیر مطابق رقوم کو مسترد کر دیتے ہیں۔ کچھ تقریبی مطابقت (ایک مقررہ رواداری کے اندر) کی اجازت دیتے ہیں اور ویب ہُک میں فرق کو ظاہر کرتے ہیں۔
  • خریدار غلط نیٹ ورک پر ادائیگی کرتا ہے۔ اگر وہ Ethereum پر دستخط کرے لیکن آپ صرف Solana قبول کرتے ہوں تو ادائیگی آپ کے ایکوائرر کی نگرانی سے مکمل طور پر چھوٹ جاتی ہے۔ زیادہ تر فراہم کنندگان بازیابی کے طریقۂ کار کے ذریعے فنڈز واپس کر دیتے ہیں؛ کچھ کے ہاں یہ ضائع ہو جاتے ہیں۔ چیک آؤٹ پر نیٹ ورک کا انتخاب واضح رکھیں۔
  • خریدار کسی ایکسچینج ایڈریس سے ادائیگی کرتا ہے۔ سورس پر ریفنڈ واپس آ سکتے ہیں یا غلط اکاؤنٹ میں جا سکتے ہیں۔ جس پروڈکٹ پر ریفنڈ کا امکان ہو، اس کے لیے چیک آؤٹ پر واضح طور پر ریفنڈ کی منزل کا ایڈریس جمع کریں۔
  • اسٹیبل کوائن کا ڈی پیگ۔ نایاب لیکن حقیقی۔ اگر کوٹ اور آن چین سیٹلمنٹ کے درمیان مختصر وقفے میں USDC نمایاں طور پر ڈی پیگ ہو جائے تو معاہدے کے لحاظ سے فرق مرچنٹ یا ایکوائرر برداشت کرتا ہے۔

DPT Acquiring کے ساتھ USDC چیک آؤٹ شامل کریں

فی ٹرانزیکشن 0.3% سے شروع۔ USDC یا فیاٹ میں اسی دن سیٹلمنٹ۔ ہوسٹڈ چیک آؤٹ URL یا ایمبیڈ کیا جا سکنے والا ویجیٹ۔ SDK اور ویب ہُک کی دستاویزات merchant.dpt.xyz پر۔

DPT Acquiring · Shopify اور WooCommerce انٹیگریشن کے طریقے