Protocore
যোগাযোগ করুন

ডেভেলপারদের জন্য

তিনটি কল আর একটি webhook।

Gateway একটি hosted checkout, তাই ইন্টিগ্রেশন ইচ্ছে করেই ছোট রাখা হয়েছে: অর্ডার তৈরি করুন, গ্রাহককে পেজে পাঠান, সাইন করা ফলাফল যাচাই করুন। নিচে যা আছে সেটাই পুরো সারফেস — পেমেন্ট UI, মেথড লজিক, 3-D Secure, ওয়ালেট ও রিসিপ্ট তৈরি করা এবং হালনাগাদ রাখা আমাদের কাজ।

স্যান্ডবক্স অ্যাক্সেসের অনুরোধ করুনcheckout ব্যবহার করে দেখুন

কাঠামো

যার সঙ্গে আপনি ইন্টিগ্রেট করছেন।

  • HTTPS-এর ওপর REST
  • JSON ইন, JSON আউট
  • Bearer API key
  • Idempotency key
  • সাইন করা webhook
  • Replay protection
  • Test ও live মোড
  • iOS ও Android SDK
  • স্টোর প্লাগইন
  • Embedded ফিল্ড

কুইকস্টার্ট

শূন্য থেকে পেইড অর্ডার পর্যন্ত।

পুরো happy path। অ্যামাউন্ট minor unit-এ, রেফারেন্স আপনার নিজের, আর গ্রাহককে redirect করতে হবে checkout URL-এ। API base URL আপনার sandbox key-এর সঙ্গে দেওয়া হয়; সেটি PROTOCORE_API_BASE হিসেবে export করুন, নিচের কলগুলো ঠিক যেমন লেখা আছে তেমনই চলবে।

01

অর্ডার তৈরি করুন

অ্যামাউন্ট, কারেন্সি ও আপনার নিজের রেফারেন্স দিয়ে একটি কল। Idempotency key আপনি নিজেই তৈরি করবেন — রিট্রাই করা রিকোয়েস্ট দ্বিতীয় অর্ডার না বানিয়ে মূল অর্ডারটিই ফেরত দেয়।

POST /v1/orders
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
  -H "Authorization: Bearer $PROTOCORE_API_KEY" \
  -H "Idempotency-Key: 9F21-0716" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 4900,
        "currency": "EUR",
        "reference": "9F21-0716",
        "line_items": [
          { "name": "Brand identity sprint", "amount": 3850 },
          { "name": "Typeface licensing",   "amount": 600 },
          { "name": "Rush delivery",        "amount": 400 }
        ],
        "return_url": "https://arcstudio.ro/thanks"
      }'
02

গ্রাহককে checkout-এ পাঠান

রেসপন্সে আপনার নিজস্ব checkout হোস্টের একটি checkout URL থাকে — sandbox-এর সঙ্গে দেওয়া হোস্ট, অথবা ডোমেইন আমাদের দিকে পয়েন্ট করার পর আপনার নিজের ডোমেইন। সেখানে redirect করুন, কিংবা SDK-তে খুলুন; মেথড, ওয়ালেট ও 3-D Secure সবই ওই পেজে আছে, তাই আপনার দিকে কিছু বানাতে হবে না।

201 Created
{
  "id": "ord_2h4Kq9wRz",
  "reference": "9F21-0716",
  "amount": 4900,
  "currency": "EUR",
  "status": "pending",
  "checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}
03

সাইন করা ফলাফল যাচাই করুন

পেমেন্ট সম্পন্ন হলে আপনার endpoint-এ একটি সাইন করা ইভেন্ট পৌঁছায়। কিছু বিশ্বাস করার আগে webhook secret দিয়ে signature যাচাই করুন, তারপর আপনার জানা রেফারেন্স ধরে অর্ডার পূরণ করুন।

POST /your/webhook — order.paid
{
  "type": "order.paid",
  "id": "evt_7Ka2Lm",
  "created": "2026-07-23T09:41:02Z",
  "data": {
    "id": "ord_2h4Kq9wRz",
    "reference": "9F21-0716",
    "amount": 4900,
    "currency": "EUR",
    "method": "usdc",
    "settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
  }
}

রেফারেন্স

যে endpoint গুলো আপনি আসলে ব্যবহার করবেন।

ডক্সে আরও অনেক কিছু আছে, তবে বেশির ভাগ ইন্টিগ্রেশন এই সেটের বাইরে যায় না।

POST /v1/orders
অর্ডার তৈরি করুন এবং তার checkout URL পান। Idempotency key নেয়।
GET /v1/orders/:id
অর্ডারের বর্তমান অবস্থা — status, method, settlement ও refund।
POST /v1/orders/:id/refunds
অর্ডারের বিপরীতে refund, পূর্ণ বা আংশিক, কারণ উল্লেখ বাধ্যতামূলক।
POST /v1/orders/:id/void
Settlement-এর আগেই authorization ছেড়ে দিন, ফলে কোনো অর্থই নড়ে না।
POST /v1/links
পেমেন্ট লিংক তৈরি করুন — একবার ব্যবহারযোগ্য বা সংগ্রহমূলক, ঐচ্ছিক মেয়াদসহ।
GET /v1/payouts/:id
একটি settlement batch এবং যেসব অর্ডার থেকে তা হয়েছে, ফি আলাদা করে দেখানো।
POST /v1/customers/:id/cards
ওয়ান-ক্লিক ও recurring চার্জের জন্য কার্ড vault করুন; একটি token রেফারেন্স ফেরত দেয়।
POST /v1/subscriptions
Vault করা কার্ডে নির্ধারিত সময়ে চার্জ করুন; প্রতিটি সাইকেল নিজস্ব অর্ডার তৈরি করে।

Webhook

আপনার backend যা শুনতে পায়।

প্রতিটি ইভেন্টে আপনার তৈরি করা অর্ডার রেফারেন্স থাকে, তাই আপনার হ্যান্ডলার হতে পারে type-এর ওপর একটি switch আর নিজের দিকে একটি lookup।

order.paid
Authorization ও capture সফল হয়েছে — রেফারেন্স ধরে অর্ডার পূরণ করুন।
order.failed
পেমেন্ট সম্পন্ন হয়নি, সঙ্গে এমন কারণ যার ওপর অপারেটর ব্যবস্থা নিতে পারেন।
order.refunded
Refund দেওয়া হয়েছে, পূর্ণ বা আংশিক, কারণ ও নোটসহ।
order.disputed
Chargeback খোলা হয়েছে, অর্ডারে আগে থেকে সংযুক্ত প্রমাণসহ।
payout.settled
একটি settlement batch আপনার অ্যাকাউন্টে রওনা হয়েছে, সঙ্গে সংশ্লিষ্ট অর্ডারের তালিকা।
subscription.charged
একটি recurring সাইকেল নিজস্ব অর্ডার ও রিসিপ্ট তৈরি করেছে।
যাচাই

বডি বিশ্বাস করার আগে signature দেখে নিন।

প্রতিটি ডেলিভারিতে একটি timestamp এবং raw body-র ওপর HMAC signature থাকে। Constant time-এ তুলনা করুন, আপনার tolerance window-এর চেয়ে পুরোনো সবকিছু বাতিল করুন, আর একই ইভেন্ট id আবার এলে সেটি আগেই সামলানো হয়েছে ধরে নিন — non-2xx রেসপন্সে আমরা retry করি, তাই আপনার হ্যান্ডলারও idempotent হওয়া উচিত।

Node — signature যাচাই
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;

  // Reject replays outside a five-minute window.
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

গ্যারান্টি

যেসব বৈশিষ্ট্যের ওপর আপনি নির্ভর করতে পারেন।

01

Idempotent তৈরি

প্রতিটি অর্ডার তৈরিতে একটি idempotency key লাগে। টাইমআউট, ডিপ্লয় বা queue redelivery-র পর রিট্রাই করা রিকোয়েস্ট দুবার চার্জ না করে মূল অর্ডারটিই ফেরত দেয়।

02

সাইন করা, replay-protected ইভেন্ট

Webhook-এ timestamp-যুক্ত HMAC signature এবং একটি স্থির ইভেন্ট id থাকে। আপনার endpoint 2xx না দেওয়া পর্যন্ত backoff-সহ ডেলিভারি retry হয়, তাই ডিপ্লয়ের সময়ে কোনো পেমেন্ট হারায় না।

03

একটি রেফারেন্স, শুরু থেকে শেষ পর্যন্ত

তৈরির সময় আপনার দেওয়া রেফারেন্স checkout, রিসিপ্ট, webhook, payout এবং পরবর্তী যেকোনো refund-এ দেখা যায়। সিস্টেমগুলোর মধ্যে মেলানোর জন্য দ্বিতীয় কোনো আইডেন্টিফায়ার নেই।

04

Test মোডও একই কোড পাথ

Test key একই ফ্লো test সেশনের বিপরীতে চালায়। Test-এ যা পাস করে, সেটাই প্রোডাকশনে যায় — পার্থক্য শুধু কোন key পাঠাচ্ছেন, কোন endpoint কল করছেন তাতে নয়।

checkout ব্যবহার করে দেখুন

টেস্ট ডেটা

গুরুত্বপূর্ণ পাথগুলো কীভাবে যাচাই করবেন।

নিচের প্রতিটি পথের জন্য একটি test card রয়েছে, sandbox ইস্যু করার সময় আপনার keys-এর সঙ্গে সেগুলো দেওয়া হয়। কার্ড নম্বর এখানে প্রকাশ করা হয় না, কারণ নম্বর প্রতিটি sandbox-এর জন্য আলাদা; ফলে scheme-এর test range বদলালেও সেগুলো সঠিক থাকে। আচরণ সব ক্ষেত্রেই নির্ধারিত (deterministic): সফল লেনদেনের মতোই সহজে decline-এর ওপরও test assert করা যায়।

সরাসরি approved
3-D Secure challenge ছাড়াই authorize ও capture হয় — happy path।
3-D Secure challenge
একটি challenge বাধ্যতামূলক করে, যা আপনি সম্পন্ন করতে পারবেন; ফলে return leg পরীক্ষা করা যায়।
Soft decline
অপর্যাপ্ত ব্যালেন্সের কারণে decline হয়, তারপর বিকল্প route-এ আবার চেষ্টা করে।
Hard decline
মেয়াদোত্তীর্ণ কার্ড হিসেবে স্থায়ীভাবে decline হয়, কোনো retry নেই।
USDC test network
Ethereum, Base ও Solana-তে test-net USDC, নির্দিষ্ট রেটে মূল্য নির্ধারিত।
Transfer simulation
একটি test vIBAN transfer-কে arrived হিসেবে চিহ্নিত করলে অর্ডারটি paid অবস্থায় যায়।

Keys নিন, শুরু করুন।

API keys, webhook secrets ও সব method চালু করা একটি sandbox merchant — সঙ্গে সম্পূর্ণ reference, যাতে কিছু স্বাক্ষরের আগেই আপনার টিম integrate করতে পারে।

স্যান্ডবক্স অ্যাক্সেসের অনুরোধ করুনcontact@protocore.io