Payment integration — gateway flow, webhook আর idempotency

১ · টাকা নেওয়ার পথ — hosted checkout-এর মানচিত্র

“বাজারঘর”-এ এখন cart আছে, order আছে, stock-এর transaction-ও আছে (পর্ব ৪৩)। বাকি একটি কাজ, আর সেটিই সবচেয়ে স্পর্শকাতর: টাকা নেওয়া। এখানে ভুলের দাম সরাসরি টাকায়। ক্রেতার টাকা কাটা গেল কিন্তু order নিশ্চিত হলো না, অথবা টাকা আসেনি অথচ ইলিশ পাঠিয়ে দেওয়া হলো। দুটিই বাস্তবে ঘটে, আর দুটিই এড়ানো যায় যদি পথটি ঠিকভাবে বোঝেন।

এই ধরনকে বলে hosted checkout. দোকানের পাতায় কার্ড নম্বর বা ওয়ালেটের PIN লেখার ঘর থাকে না। Payment gateway নিজের পাতা দেখায়, OTP বা PIN নেয়, ব্যাংক বা ওয়ালেটের সাথে কথা বলে। দোকানের server শুধু তিনটি কাজ করে: (১) টাকার পরিমাণ ঠিক করে session বানায়, (২) ক্রেতাকে সেই পাতায় পাঠায়, (৩) ফলাফলের খবর যাচাই করে order-এর অবস্থা বদলায়। নিচের ছবিতে পুরো পথ।

বাংলাদেশে অনেক gateway আর MFS এই ছাঁচের কোনো না কোনো রূপ ব্যবহার করে। উদাহরণ হিসেবে, লেখার সময়ে SSLCommerz-এর প্রকাশ্য developer docs (v4) বর্ণনা করে: server থেকে একটি session API ডাকা, উত্তরে একটি GatewayPageURL, success, fail আর cancel URL, একটি ঐচ্ছিক কিন্তু প্রস্তাবিত IPN listener, আর একটি order validation API, যার মাধ্যমে পরিমাণ আর অবস্থা নিশ্চিত করার পরামর্শ দেওয়া হয়। bKash, Nagad আর অন্য MFS-এর নিজস্ব developer portal আছে; সেখানে ক্রেতা সাধারণত সেবাদাতার নিজের পাতায় বা অ্যাপে অনুমোদন দেন। প্রতিটির API-র নাম, ধাপ, স্বাক্ষরের ধরন, মেয়াদ আর খরচ আলাদা আর সময়ের সাথে বদলায়। এই পর্বে সেগুলোর কোনো API নকল করা হয়নি, আর কোনো খরচের হিসাবও দেওয়া হচ্ছে না। কাজ শুরুর আগে আপনার বাছাই করা সেবার সর্বশেষ অফিসিয়াল docs আর চুক্তি পড়বেন।

২ · ল্যাবের নকল gateway — BazarPay আর test mode-এর অভ্যাস

আসল gateway-তে পরীক্ষা মানে আসল account, আসল key আর নিয়মের বাধ্যবাধকতা। শেখার জন্য আমরা নিজেই একটি ছোট gateway বানিয়েছি: BazarPay. এটি একটি শিক্ষার জন্য বানানো নকল সেবা, কোনো বাস্তব প্রতিষ্ঠানের API নয়, আর এর URL, header বা field-এর নাম কোনো বাস্তব gateway-তে কাজ করবে না। কাজটি কিন্তু বাস্তবের মতো: Express 5 দিয়ে আলাদা port-এ চলে, session বানায়, hosted পাতা দেখায়, HMAC স্বাক্ষরসহ webhook পাঠায়, ব্যর্থ হলে retry করে, আর একটি validation API দেয়।

ল্যাবের retry-র সময় ইচ্ছা করে ছোট রাখা হয়েছে, যাতে কয়েক সেকেন্ডে সব দেখা যায়। বাস্তব gateway সাধারণত মিনিট থেকে ঘণ্টা, এমনকি দিনের পর দিন ধরে retry করে, ক্রমশ বাড়ানো বিরতিতে (exponential backoff); সঠিক সূচি তাদের docs-এ থাকে। ল্যাবে খারাপ দিন বানানোর জন্য কয়েকটি শুধু-ল্যাবের সুইচও আছে: webhook ফেলে দেওয়া, দুবার পাঠানো, উল্টো ক্রমে পাঠানো, আর session-এর মেয়াদ ছোট করা।

এই পর্বের প্রতিটি আউটপুট একটি সত্যিকারের ল্যাব থেকে। লেখার সময়ের version: Node 24.15.0, Express 5.3.0, Prisma 7.10.1 আর @prisma/adapter-pg 7.10.1 (npm-এ prisma-র latest তখন 8.0.0-এর release candidate ছিল, তাই সর্বশেষ stable 7.10.1 নেওয়া হয়েছে), PostgreSQL চলেছে portable embedded-postgres 18.6.0-beta.19 দিয়ে, log-এর জন্য pino 10.4.0, আর browser চালাতে Playwright 1.64.1, Microsoft Edge-এ। তিনটি server-ই শুধু 127.0.0.1-এ: gateway 47651, দোকান 47652, database 47653. Key আর secret সব নকল: sk_test_example, whsec_test_example. Version বদলায়, তাই নিজের package.json মিলিয়ে নেবেন।

৩ · অবস্থার যন্ত্র — order আর payment, PostgreSQL আর Prisma-য়

প্রথম নকশার সিদ্ধান্ত: order আর payment আলাদা টেবিল। একটি order-এর একাধিক payment চেষ্টা হতে পারে (প্রথমটি ব্যর্থ, দ্বিতীয়টি সফল), আর cash on delivery-র order-এ online payment থাকেই না। প্রতিটির নিজের অবস্থা, আর অবস্থা বদলের নিয়ম একটি state machine. নিয়মটি কাগজে আঁকুন আগে, কোড পরে।

এখন Prisma schema. দাম রাখা হয়েছে minor unit-এ, অর্থাৎ পয়সায়, পূর্ণসংখ্যা হিসেবে: ৳২৫০০ মানে 250000. কেন floating point নয়, সে আলোচনা আর প্রমাণ আছে পর্ব ৩২-এর টাকার representation অংশে। অবস্থাগুলো PostgreSQL-এর enum, তাই database নিজেই অচেনা মান আটকায়।

enum PaymentStatus {
  PENDING
  AUTHORISED
  PAID
  FAILED
  EXPIRED
  PARTIALLY_REFUNDED
  REFUNDED
}

model Payment {
  id             Int           @id @default(autoincrement())
  order          Order         @relation(fields: [orderId], references: [id])
  orderId        Int
  provider       String        // "bazarpay" বা "cod"
  sessionId      String?       @unique
  amountPaisa    Int
  currency       String
  status         PaymentStatus @default(PENDING)
  refundedPaisa  Int           @default(0)
  idempotencyKey String        @unique   // session তৈরির key
  lastEventAt    DateTime?
  createdAt      DateTime      @default(now())
  updatedAt      DateTime      @updatedAt
  refunds        Refund[]
}

model WebhookEvent {
  id         String   @id          // gateway-র event id: duplicate আটকানোর দেয়াল
  type       String
  sessionId  String
  outcome    String
  receivedAt DateTime @default(now())
}

Order-এ আছে ref (unique), totalPaisa, method (ONLINE বা COD) আর নিজের অবস্থা AWAITING_PAYMENT, CONFIRMED, CANCELLED; Refund আর OutboxEvent টেবিলও আছে। prisma migrate dev-এর তৈরি SQL থেকে দুটি অংশ, সত্যিকারের run:

$ npx prisma migrate dev --name payments
Datasource "db": PostgreSQL database "bazarghar_pay", schema "public" at "127.0.0.1:47653"
Applying migration `20261102181004_payments`
Your database is now in sync with your schema.

-- migration.sql থেকে
CREATE TYPE "PaymentStatus" AS ENUM ('PENDING', 'AUTHORISED', 'PAID', 'FAILED', 'EXPIRED', 'PARTIALLY_REFUNDED', 'REFUNDED');
CREATE UNIQUE INDEX "Payment_sessionId_key" ON "Payment"("sessionId");
CREATE UNIQUE INDEX "Payment_idempotencyKey_key" ON "Payment"("idempotencyKey");
CREATE UNIQUE INDEX "Refund_idempotencyKey_key" ON "Refund"("idempotencyKey");

Enum শুধু বলে কোন মানগুলো বৈধ। কোন অবস্থা থেকে কোথায় যাওয়া যায়, সেই নিয়ম কোডে। নিচের ব্লকে ল্যাবের একই নিয়ম, একটি ছোট রূপে। কয়েকটি বৈধ আর কয়েকটি অবৈধ ধাপ চেষ্টা করা হয়েছে।

// পেমেন্টের অবস্থার যন্ত্র: কোন অবস্থা থেকে কোথায় যাওয়া বৈধ
const NEXT = {
  PENDING: ["AUTHORISED", "PAID", "FAILED", "EXPIRED"],
  AUTHORISED: ["PAID", "FAILED", "EXPIRED"],
  PAID: ["PARTIALLY_REFUNDED", "REFUNDED"],
  PARTIALLY_REFUNDED: ["PARTIALLY_REFUNDED", "REFUNDED"],
  FAILED: [], EXPIRED: [], REFUNDED: [],          // শেষ অবস্থা: আর কোথাও নয়
};

function move(p, to, why) {
  if (!NEXT[p.status].includes(to)) {
    console.log(`  REFUSED ${p.status} -> ${to} (${why})`);
    return p;                                      // অবস্থা বদলায় না
  }
  console.log(`  ok      ${p.status} -> ${to} (${why})`);
  return { ...p, status: to };
}

let p = { ref: "BG-2045", status: "PENDING", amountPaisa: 125000 };
p = move(p, "AUTHORISED", "bank approved");
p = move(p, "PAID", "captured");
p = move(p, "PENDING", "old event replayed");
p = move(p, "FAILED", "late failure event");
p = move(p, "PARTIALLY_REFUNDED", "refund 300 taka");
p = move(p, "PAID", "someone clicked undo");
p = move(p, "REFUNDED", "refund the rest");
p = move(p, "PARTIALLY_REFUNDED", "refund again");
console.log("final:", p.status);

let q = { ref: "BG-2046", status: "PENDING" };
q = move(q, "EXPIRED", "customer left");
q = move(q, "PAID", "payment after expiry");   // টাকা কাটা গেলে মানুষের হাতে দিন

৪ · Session তৈরি — দাম server-এ, আর একই key-তে একবারই

Checkout-এর form-এ শুধু পণ্যের sku, পরিমাণ আর পদ্ধতি আসে। দাম আসে বাজারঘরের নিজের catalogue থেকে। Browser থেকে amount পাঠালেও তা উপেক্ষিত। ল্যাবে আমরা ইচ্ছা করে amount=100 পাঠিয়েছিলাম; log বলছে "ignoredBrowserAmount":"100" আর "total":42000. এটি log-এ রাখা শুধু দেখানোর জন্য; বাস্তবে এমন field এলে সন্দেহজনক অনুরোধ হিসেবে গোনা যায়।

app.post('/checkout', async (req, res) => {
  const item = CATALOGUE[req.body.sku];
  const qty = Number(req.body.qty);
  if (!item || !Number.isInteger(qty) || qty < 1 || qty > 10) return res.status(422).send('bad item');
  const total = item.pricePaisa * qty;          // দাম আমাদের catalogue থেকে, browser থেকে নয়
  const ref = `BG-${++nOrder}`;
  const order = await prisma.order.create({ data: { ref, totalPaisa: total, method: 'ONLINE',
    payments: { create: { provider: 'bazarpay', amountPaisa: total, currency: 'BDT',
      idempotencyKey: `pay_${ref}_1` } } }, include: { payments: true } });
  const pay = order.payments[0];
  // ... body: merchantRef, amountPaisa, currency, successUrl, failUrl, notifyUrl
  for (let attempt = 1; attempt <= 2 && !s; attempt++) {   // retry-তে একই key
    const r = await fetch(`${GW}/v1/sessions`, { method: 'POST', body,
      signal: AbortSignal.timeout(5000),
      headers: { 'content-type': 'application/json', authorization: `Bearer ${process.env.GATEWAY_KEY}`,
        'idempotency-key': pay.idempotencyKey } });
    if (r.ok) s = await r.json();
  }
  await prisma.payment.update({ where: { id: pay.id }, data: { sessionId: s.id } });
  res.redirect(303, s.payUrl);
});

কেন key? ধরুন বাজারঘর session চাইল, gateway session বানাল, কিন্তু উত্তর আসার আগেই network-এর সময়সীমা পার হলো। বাজারঘর জানে না session হয়েছে কি না, তাই আবার চায়। Key না থাকলে দুটি session, আর ক্রেতা দুটি আলাদা ট্যাবে দুবার টাকা দিতে পারেন। Key থাকলে gateway চিনে ফেলে, “এটি আগের অনুরোধই”, আর একই উত্তর ফেরত দেয়। এটি পর্ব ৩৩-এর idempotency key-এর হুবহু একই নীতি, শুধু এবার আমরা client, gateway server. BazarPay-কে সরাসরি curl দিয়ে চারবার জিজ্ঞেস করা হলো, সত্যিকারের run:

$ curl … /v1/sessions -H 'idempotency-key: pay_BG-2099_1' -d "$BODY"          # প্রথমবার
{"id":"sess_0008","payUrl":"http://127.0.0.1:47651/pay/sess_0008","expiresAt":"2026-11-02T18:26:45.580Z"} [201]
$ curl … একই key, একই body                                                    # retry
{"id":"sess_0008","payUrl":"http://127.0.0.1:47651/pay/sess_0008","expiresAt":"2026-11-02T18:26:45.580Z"} [200]
$ curl … একই key, কিন্তু amountPaisa 4200
{"error":"key reused with different body"} [422]
$ curl … নতুন key, amountPaisa 420.5
{"error":"amountPaisa must be a positive integer, currency BDT"} [422]
$ curl … ভুল key দিয়ে (Authorization: Bearer wrong)
{"error":"bad key"} [401]

দ্বিতীয় উত্তর 201 নয়, 200, কিন্তু একই sess_0008: নতুন কিছু তৈরি হয়নি। তৃতীয়টি বিপজ্জনক ভুল ধরেছে: একই key-তে ভিন্ন body মানে client-এর বাগ, তাই 422. চতুর্থটি দেখায় gateway ভগ্নাংশ পয়সা নেয় না। Order-এর key-টি payment-এর সারিতে unique column-এ জমা, তাই বাজারঘরের server restart হলেও একই order-এর জন্য একই key যায়।

৫ · Return URL দেখায়, webhook আর validation API সিদ্ধান্ত নেয়

Gateway-র পাতায় টাকা দেওয়ার পর ক্রেতা ফেরেন এই ঠিকানায়: /payment/return?ref=BG-2041&session=sess_0001&status=success. এই return URL browser-এর address bar দিয়ে আসে। যে কেউ নিজে status=success লিখে খুলতে পারেন। তাই বাজারঘরের return handler শুধু database-এর বর্তমান অবস্থা দেখায়, কিছু লেখে না। অপেক্ষার সময় পাতাটি প্রতি সেকেন্ডে নিজে refresh হয়।

// Return URL শুধু দেখায়। এটি কখনো কিছু paid করে না।
app.get('/payment/return', async (req, res) => {
  const ref = String(req.query.ref ?? '');
  const order = await prisma.order.findUnique({ where: { ref }, include: { payments: true } });
  if (!order) return res.status(404).send('no order');
  const p = order.payments[0];
  log.info({ ref, claimed: req.query.status ?? null, actual: p.status }, 'customer returned');
  // ... PENDING হলে <meta http-equiv="refresh" content="1">, নইলে ফলাফল
});

সিদ্ধান্ত হয় webhook-এ। Express-এ webhook route-টি express.json()-এর আগে বসানো, আর নিজে express.raw() নেয়, কারণ HMAC মেলাতে হয় হুবহু byte-এর ওপর (raw body). স্বাক্ষর, সময়সীমা আর timingSafeEqual-এর বিস্তারিত যুক্তি পর্ব ৫৭-এ; এখানে সেই একই কাজ, তারপর তিনটি নতুন ধাপ। নিচের কোড ল্যাবের ফাইল থেকে, log-এর লাইন বাদ দিয়ে আর unique violation-এর পরীক্ষা একটি ছোট helper-এ সরিয়ে সংক্ষেপ করা।

export async function applyGatewayTruth(sessionId: string, source: string, eventId?: string, eventType?: string) {
  const g = await gatewayGet(`/v1/sessions/${sessionId}`);          // ১. নিজে জিজ্ঞেস করা
  const pay = await prisma.payment.findUnique({ where: { sessionId }, include: { order: true } });
  if (!pay) return 'unknown';
  if (g.amountPaisa !== pay.amountPaisa || g.currency !== pay.currency || g.merchantRef !== pay.order.ref) {
    log.error({ ref: pay.order.ref }, 'AMOUNT/CURRENCY MISMATCH - not fulfilling, needs review');
    return 'mismatch';                                                // ২. paisa আর মুদ্রা
  }
  const to = targetFrom(g, pay.amountPaisa);
  return prisma.$transaction(async (tx) => {
    if (eventId) {                                                    // ৩. event id একবারই
      try { await tx.webhookEvent.create({ data: { id: eventId, type: eventType!, sessionId, outcome: 'applied' } }); }
      catch (e) { if (isUniqueViolation(e)) return 'duplicate'; throw e; }
    }
    if (!to || (to === pay.status && g.refundedPaisa === pay.refundedPaisa)) return 'no-change';
    if (!canMove(pay.status, to)) return 'refused';                   // state machine
    const n = await tx.payment.updateMany({ where: { id: pay.id, status: pay.status },
      data: { status: to, refundedPaisa: g.refundedPaisa, lastEventAt: new Date() } });
    if (n.count === 0) throw new Error('concurrent change, retry');
    if (to === 'PAID') {
      await tx.order.update({ where: { id: pay.orderId }, data: { status: 'CONFIRMED' } });
      await tx.outboxEvent.create({ data: { type: 'order.paid', payload: { ref: pay.order.ref } } });
    }
    return to;
  });
}

কয়েকটি সিদ্ধান্ত খেয়াল করুন। Event-এর type শুধু একটি ইঙ্গিত। আসল লক্ষ্য অবস্থা আসে validation API-র উত্তর থেকে। তাই একটি জাল কিন্তু বৈধ-স্বাক্ষরের ঘটনা থাকলেও (ধরুন secret ফাঁস হয়েছে), gateway নিজে যা বলে তার বাইরে কিছু হয় না। Event id-র জন্য unique constraint, আর order বদল, outbox, সব একই transaction-এ। updateMany-এর where-এ পুরোনো status: মাঝখানে অন্য কেউ বদলালে count হবে 0, আর পুরো transaction বাতিল হয়ে gateway-র retry-তে আবার চেষ্টা হবে। Order নিশ্চিত হলে email বা গুদামের কাজ সরাসরি নয়, outbox-এ লেখা হয় (পর্ব ৪৩-এর transactional outbox), যা পরে একটি worker পাঠায় (পর্ব ৬২)।

নিচের ব্লকে স্বাক্ষর যাচাই, duplicate বাদ আর paisa-মুদ্রা মেলানো, এক জায়গায়। একটি নির্দিষ্ট সময় ব্যবহার করা হয়েছে, যাতে ফল সবসময় এক থাকে।

const { createHmac, timingSafeEqual } = require("node:crypto");
const SECRET = "whsec_test_example";                 // নকল মান
const orders = { "BG-2042": { amountPaisa: 42000, currency: "BDT", status: "PENDING" } };
const seen = new Set();                              // বাস্তবে: unique column

const sign = (t, raw) => createHmac("sha256", SECRET).update(`${t}.${raw}`).digest("hex");

function handle(header, raw, now) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const exp = Buffer.from(sign(t, raw), "hex"), got = Buffer.from(v1 ?? "", "hex");
  if (Math.abs(now - Number(t)) > 300) return "401 too old";
  if (got.length !== exp.length || !timingSafeEqual(got, exp)) return "401 bad signature";
  const ev = JSON.parse(raw);
  if (seen.has(ev.id)) return `200 duplicate ${ev.id}`;
  seen.add(ev.id);
  const o = orders[ev.ref];
  if (!o) return "200 unknown order, flagged";
  if (ev.amountPaisa !== o.amountPaisa || ev.currency !== o.currency)
    return `200 MISMATCH ours ${o.amountPaisa} ${o.currency}, theirs ${ev.amountPaisa} ${ev.currency}: review`;
  o.status = "PAID";
  return `200 ${ev.ref} PAID (${(o.amountPaisa / 100).toFixed(2)} taka)`;
}

const now = 1793640000;
const send = (obj, at = now) => { const raw = JSON.stringify(obj);
  return [`t=${now},v1=${sign(now, raw)}`, raw, at]; };
const ok = send({ id: "evt_0004", ref: "BG-2042", amountPaisa: 42000, currency: "BDT" });
console.log("1", handle(...send({ id: "evt_0015", ref: "BG-2042", amountPaisa: 420, currency: "BDT" })));
console.log("2", handle(...send({ id: "evt_0016", ref: "BG-2042", amountPaisa: 42000, currency: "USD" })));
console.log("3", handle(...ok));
console.log("4", handle(ok[0], ok[1], now + 30));                  // retry
console.log("5", handle(ok[0], ok[1].replace("42000", "4200"), now)); // বদলানো
console.log("6", handle(ok[0], ok[1], now + 900));
console.log("status:", orders["BG-2042"].status);

Edge-এ একটি পূর্ণ checkout, সত্যিকারের run

এবার পুরো পথ আসল browser-এ। Playwright-এর একটি ছোট end-to-end script Microsoft Edge খুলে (chromium.launch({ channel: 'msedge' })) বাজারঘরের পাতায় দুই কেজি ইলিশ বেছে “Place order” চাপে, BazarPay-এর পাতায় “Pay (test)” চাপে, তারপর ফিরে আসা পাতায় অবস্থা পড়ে। Playwright-এর পূর্ণ আলোচনা পর্ব ৭৬-এ (End-to-end test — Playwright আর নির্ভরযোগ্য selector).

$ node e2e/checkout.mjs
[edge] at http://127.0.0.1:47652/
[edge] at http://127.0.0.1:47651/pay/sess_0001
[edge] hosted page says: Pay 2500.00 BDT to BG-2041
[edge] at http://127.0.0.1:47652/payment/return?ref=BG-2041&session=sess_0001&status=success
[edge] first view : payment: PENDING, order: AWAITING_PAYMENT
[edge] at http://127.0.0.1:47652/payment/return?ref=BG-2041&session=sess_0001&status=success
[edge] final view : payment: PAID, order: CONFIRMED

একই সময়ে দুই server-এর log. pino প্রতিটি লাইন JSON-এ লেখে; একটি লাইন হুবহু এমন:

{"level":"info","time":"2026-11-02T18:10:20.111Z","svc":"shop","evt":"evt_0001","type":"payment.authorised","ref":"BG-2041","from":"PENDING","to":"PAID","source":"webhook","msg":"payment moved"}

পড়ার সুবিধায় বাকিগুলো সময়, service, বার্তা আর মূল field রেখে এক লাইনে সাজানো হলো; মান কিছু বদলানো হয়নি।

18:10:19.956 shop     order created                    ref=BG-2041 total=250000 method=ONLINE
18:10:19.981 gateway  session created                  key=pay_BG-2041_1 session=sess_0001 amountPaisa=250000
18:10:19.990 shop     redirecting customer to hosted page  ref=BG-2041 session=sess_0001
18:10:20.066 gateway  customer finished on hosted page session=sess_0001 outcome=success
18:10:20.070 shop     customer returned                ref=BG-2041 claimed=success actual=PENDING
18:10:20.096 shop     webhook verified                 evt=evt_0001 type=payment.authorised
18:10:20.097 gateway  validation API called            session=sess_0001 status=succeeded
18:10:20.111 shop     payment moved                    evt=evt_0001 from=PENDING to=PAID source=webhook
18:10:20.115 gateway  webhook delivered                evt=evt_0001 attempt=1 status=200
18:10:20.380 shop     webhook verified                 evt=evt_0002 type=payment.succeeded
18:10:20.384 shop     no change                        evt=evt_0002 status=PAID source=webhook
18:10:21.086 shop     customer returned                ref=BG-2041 claimed=success actual=PAID

সবচেয়ে গুরুত্বপূর্ণ লাইন claimed=success actual=PENDING. ক্রেতা ফেরার মুহূর্তে browser “success” বলছিল, কিন্তু server তখনো কিছু জানত না, আর বিশ্বাসও করেনি। ২৬ মিলিসেকেন্ড পরে webhook এলো, যাচাই হলো, তারপর PAID. আরেকটি মজার জিনিস: প্রথম ঘটনার type ছিল payment.authorised, তবু অবস্থা সরাসরি PAID, কারণ validation API তখনই বলছিল succeeded. দ্বিতীয় ঘটনা payment.succeeded এসে দেখল কিছু করার নেই।

Order   BG-2041  total=250000  AWAITING_PAYMENT
Payment PENDING  amountPaisa=250000  BDT
        idempotencyKey=pay_BG-2041_1
        sessionId=null

{"id":"sess_0001",
 "payUrl":"…/pay/sess_0001"}
Payment.sessionId = sess_0001
303 → payUrl

TEST MODE - fake gateway, no real money
Pay 2500.00 BDT to BG-2041
[Pay (test)]  [Fail (test)]

?ref=BG-2041&status=success
log: claimed=success actual=PENDING
পাতা: payment: PENDING, order: AWAITING_PAYMENT

HMAC + সময়সীমা → ঠিক
validation API → succeeded, 250000, BDT
আমাদের সারি   → 250000, BDT  ✓
PENDING → PAID, Order → CONFIRMED

OutboxEvent order.paid {ref: BG-2041}
evt_0002 payment.succeeded → no change
পাতা refresh: payment: PAID, order: CONFIRMED

৬ · Duplicate, দেরিতে আর উল্টো ক্রমে আসা webhook

Webhook পাঠানো হয় at-least-once নীতিতে: gateway 2xx না পেলে আবার পাঠায়। ফলে তিন রকম বিশৃঙ্খলা স্বাভাবিক। একই ঘটনা দুবার। একটি ঘটনা অনেক দেরিতে, যখন অবস্থা অন্য পথে বদলে গেছে। আর উল্টো ক্রম: পরে ঘটা ঘটনার খবর আগে। ল্যাবের সুইচ দিয়ে তিনটিই ঘটানো হলো।

(ক) একই ঘটনা একসাথে দুবার। BazarPay-কে বলা হলো প্রতিটি webhook দুই কপি পাঠাতে, প্রায় একই মিলিসেকেন্ডে। Order BG-2042, সত্যিকারের run-এর log, সাজানো:

18:10:36.396 shop  webhook verified   evt=evt_0003 type=payment.authorised
18:10:36.396 shop  webhook verified   evt=evt_0003 type=payment.authorised
18:10:36.402 shop  payment moved      evt=evt_0003 from=PENDING to=PAID source=webhook
18:10:36.434 shop  duplicate event, nothing changed   evt=evt_0003
18:10:36.698 shop  webhook verified   evt=evt_0004 type=payment.succeeded
18:10:36.699 shop  webhook verified   evt=evt_0004 type=payment.succeeded
18:10:36.703 shop  no change          evt=evt_0004 status=PAID
18:10:36.704 shop  duplicate event, nothing changed   evt=evt_0004

দুটি কপি একই মিলিসেকেন্ডে যাচাই পেরিয়েছে। একটি WebhookEvent-এ evt_0003 লিখে order বদলেছে। অন্যটি একই id লিখতে গিয়ে PostgreSQL-এর unique index-এ অপেক্ষা করেছে, প্রথমটি commit হতেই P2002 (unique violation) পেয়ে থেমেছে। Memory-র একটি Set এখানে কাজ করত না, কারণ দুটি অনুরোধ একসাথে চলছিল, আর বাস্তবে server-এর একাধিক কপি থাকে।

(খ) উল্টো ক্রম, আর বাজারঘরের endpoint দুবার বন্ধ। এবার gateway succeeded আগে, authorised পরে পাঠাল, আর বাজারঘর প্রথম দুটি অনুরোধে ইচ্ছা করে 503 দিল:

18:10:39.155 gateway webhook delivered  evt=evt_0006 type=payment.succeeded  attempt=1 status=503
18:10:39.458 gateway webhook delivered  evt=evt_0005 type=payment.authorised attempt=1 status=503
18:10:39.674 shop    payment moved      evt=evt_0006 from=PENDING to=PAID source=webhook
18:10:39.675 gateway webhook delivered  evt=evt_0006 type=payment.succeeded  attempt=2 status=200
18:10:39.975 shop    no change          evt=evt_0005 type=payment.authorised status=PAID
18:10:39.976 gateway webhook delivered  evt=evt_0005 type=payment.authorised attempt=2 status=200

(Gateway-র বার্তার লেখা “webhook delivered” প্রতিটি চেষ্টার পরে লেখা হয়; আসল ফল status-এ। 503 মানে চেষ্টা ব্যর্থ, তাই retry.) প্রথম চেষ্টা ব্যর্থ, আধা সেকেন্ড পরে দ্বিতীয় চেষ্টায় সফল। আর দেরিতে আসা payment.authorised PAID order-কে পিছিয়ে দেয়নি, কারণ PAID থেকে AUTHORISED-এ যাওয়ার কোনো পথ যন্ত্রে নেই।

আমাদের ল্যাব প্রতিবার validation API জিজ্ঞেস করে, তাই উল্টো ক্রম নিজে থেকেই মিটে যায়। কিন্তু সব gateway প্রতিটি ঘটনার পরে API ডাকার সুযোগ দেয় না, বা প্রতিবার ডাকা খরচের হতে পারে। তখন ঘটনার নিজের তথ্য দিয়েই সিদ্ধান্ত: অবস্থার rank, আর একই rank-এ ঘটার সময় (occurredAt, পৌঁছানোর সময় নয়)। নিচের ব্লকে একটি payment-এর ছয়টি ঘটনা এলোমেলো ক্রমে আসে।

// উল্টো ক্রমে আসা ঘটনা: rank আর ঘটার সময় (occurredAt) দিয়ে সিদ্ধান্ত
const RANK = { PENDING: 0, AUTHORISED: 1, FAILED: 2, PAID: 3, PARTIALLY_REFUNDED: 4, REFUNDED: 5 };

function apply(p, ev) {
  const newer = ev.at > p.lastAt;
  const up = RANK[ev.status] > RANK[p.status];
  const sameButNewer = ev.status === p.status && newer;     // যেমন দুটি partial refund
  if (!up && !sameButNewer) return { ...p, note: `ignored ${ev.id} ${ev.status}@${ev.at}` };
  return { status: ev.status, refunded: ev.refunded ?? p.refunded,
    lastAt: Math.max(p.lastAt, ev.at), note: `applied ${ev.id} ${ev.status}@${ev.at}` };
}

// ঘটেছে এই ক্রমে (at = সেকেন্ড), কিন্তু পৌঁছেছে নিচের ক্রমে
const arrivals = [
  { id: "e2", status: "PAID", at: 102 },
  { id: "e5", status: "PARTIALLY_REFUNDED", refunded: 80000, at: 260 },
  { id: "e1", status: "AUTHORISED", at: 101 },
  { id: "e4", status: "PARTIALLY_REFUNDED", refunded: 30000, at: 200 },
  { id: "e0", status: "FAILED", at: 95 },            // আগের একটি ব্যর্থ চেষ্টা, দেরিতে
  { id: "e6", status: "REFUNDED", refunded: 125000, at: 300 },
];

let p = { status: "PENDING", refunded: 0, lastAt: 0 };
for (const ev of arrivals) {
  p = apply(p, ev);
  console.log(p.note.padEnd(36), "=>", p.status, p.refunded);
}

// সময়ের ক্রম ধরে চালালে একই শেষ অবস্থা আসে কি না
let q = { status: "PENDING", refunded: 0, lastAt: 0 };
for (const ev of [...arrivals].sort((a, b) => a.at - b.at)) q = apply(q, ev);
console.log("in time order  =>", q.status, q.refunded, "| same?", q.status === p.status && q.refunded === p.refunded);

INSERT WebhookEvent id=evt_0003  ✓
Payment PENDING → PAID
Order → CONFIRMED, outbox order.paid
উত্তর 200

INSERT WebhookEvent id=evt_0003
→ unique index-এ অপেক্ষা, তারপর P2002
"duplicate event, nothing changed"
উত্তর 200

07.675 evt_0009 attempt=1 → 503
07.964 evt_0010 attempt=1 → 503
08.176 / 08.479   attempt=2 → 503
09.192 / 09.495   attempt=3 → 503
Payment তখনো PENDING

stuck payments found: 1
validation API → succeeded
PENDING → PAID source=reconcile

evt_0009 authorised → no change (PAID)
evt_0010 succeeded  → no change (PAID)
outbox-এ order.paid মোট ১টি

৭ · টাকা কাটা গেল, খবর এলো না — timeout আর reconciliation

সবচেয়ে কষ্টের অভিযোগ: “আমার টাকা কেটেছে, কিন্তু order দেখাচ্ছে বাকি”। কারণ অনেক রকম হতে পারে: webhook হারিয়েছে, আপনার server তখন deploy হচ্ছিল, firewall আটকেছে, বা secret বদলের পরে স্বাক্ষর মিলছিল না। ক্রেতার কাছে সব একই। সমাধান হলো reconciliation: নিজে থেকে নিয়মিত gateway-কে জিজ্ঞেস করা।

কাজটির দুটি অংশ। এক, দ্রুত সারানো: যেসব payment কয়েক মিনিটের বেশি PENDING বা AUTHORISED, তাদের প্রতিটির জন্য validation API ডেকে applyGatewayTruth চালানো, webhook-এর একই ফাংশন। দুই, দিনের শেষে মেলানো: gateway-র পুরো settlement report নিয়ে প্রতিটি সারির অবস্থা আর পরিমাণ মিলিয়ে দেখা। Job কীভাবে নির্দিষ্ট সময়ে চালাবেন, queue বা cron দিয়ে, তা পর্ব ৬২ (Background job — queue, retry আর cron)-এর বিষয়। এখানে job-এর ভেতরের যুক্তি।

ল্যাবে BazarPay-কে বলা হলো সব webhook ফেলে দিতে। ক্রেতা টাকা দিলেন, তিন সেকেন্ড পরেও order বাকি। তারপর reconcile job চালানো হলো, সত্যিকারের run:

== C paid, webhooks dropped
checkout -> http://127.0.0.1:47651/pay/sess_0004
hosted page -> http://127.0.0.1:47652/payment/return?ref=BG-2044&session=sess_0004&status=success
after 3 s:
{"ref":"BG-2044","order":"AWAITING_PAYMENT","payment":"PENDING","amountPaisa":84000,"refundedPaisa":0}

$ node --import tsx src/reconcile.ts 2        # ২ সেকেন্ডের বেশি পুরোনো PENDING
{"level":"info",…,"svc":"reconcile","count":1,"olderThanSec":2,"msg":"reconcile: stuck payments found"}
{"level":"info",…,"svc":"reconcile","ref":"BG-2044","from":"PENDING","to":"PAID","source":"reconcile","msg":"payment moved"}
BG-2041  sess_0001  gateway=PAID               ours=PAID               OK
BG-2042  sess_0002  gateway=PAID               ours=PAID               OK
BG-2043  sess_0003  gateway=PAID               ours=PAID               OK
BG-2044  sess_0004  gateway=PAID               ours=PAID               OK
report rows=4 mismatches=0

সব পরীক্ষার শেষে আরেকবার পুরো report মেলানো হলো। এবার একটি অমিল ধরা পড়ল, আর সেটি সত্যিই একটি তদন্তের বিষয়:

BG-2045  sess_0005  gateway=REFUNDED           ours=REFUNDED           OK
BG-2046  sess_0006  gateway=EXPIRED            ours=EXPIRED            OK
BG-2047  sess_0007  gateway=FAILED             ours=FAILED             OK
BG-2099  sess_0008  gateway=PENDING            ours=MISSING            MISMATCH
report rows=8 mismatches=1

sess_0008 আমরা সেকশন ৪-এ curl দিয়ে সরাসরি gateway-তে বানিয়েছিলাম, বাজারঘরের database ছাড়াই। Gateway-তে আছে, আমাদের কাছে নেই। বাস্তবে এমন অমিল মানে হতে পারে: session বানানোর পরে database-এ লেখার আগেই server পড়ে গেছে, বা কেউ অন্য পথে API key ব্যবহার করছেন। দুটিই জানা দরকার।

1// ক্রেতা টাকা দিয়েছেন, webhook হারিয়েছে2const stuck = await prisma.payment.findMany({3  where: { status: { in: ['PENDING','AUTHORISED'] },4           createdAt: { lt: cutoff } } });5for (const p of stuck) {6  await applyGatewayTruth(p.sessionId, 'reconcile');7}8const report = await gatewayGet('/v1/reports/…');9// প্রতিটি সারি মেলানো, অমিল গোনা

পরের ব্লকে দিনের শেষের মেলানোটি, একটু বেশি অমিলসহ। প্রতিটি অমিলের জন্য আলাদা পদক্ষেপ।

// দিনের শেষে মিলানো: আমাদের payment টেবিল বনাম gateway-র report
const ours = [
  { ref: "BG-2041", session: "sess_0001", status: "PAID", paisa: 250000 },
  { ref: "BG-2044", session: "sess_0004", status: "PENDING", paisa: 84000 },
  { ref: "BG-2050", session: "sess_0010", status: "PAID", paisa: 42000 },
  { ref: "BG-2051", session: "sess_0011", status: "PAID", paisa: 125000 },
  { ref: "BG-2052", session: "sess_0012", status: "EXPIRED", paisa: 42000 },
];
const report = [
  { session: "sess_0001", status: "succeeded", paisa: 250000 },
  { session: "sess_0004", status: "succeeded", paisa: 84000 },
  { session: "sess_0011", status: "succeeded", paisa: 12500 },
  { session: "sess_0012", status: "expired", paisa: 42000 },
  { session: "sess_0013", status: "succeeded", paisa: 42000 },
];
const MAP = { succeeded: "PAID", failed: "FAILED", expired: "EXPIRED" };
const bySession = new Map(report.map((r) => [r.session, r]));
const action = [];

for (const o of ours) {
  const g = bySession.get(o.session);
  bySession.delete(o.session);
  if (!g) action.push(`${o.ref}: we say ${o.status}, gateway has nothing -> hold delivery, investigate`);
  else if (g.paisa !== o.paisa) action.push(`${o.ref}: amount ours ${o.paisa}, theirs ${g.paisa} -> review`);
  else if (MAP[g.status] !== o.status) action.push(`${o.ref}: ours ${o.status}, gateway ${MAP[g.status]} -> re-check via validation API`);
}
for (const g of bySession.values()) action.push(`${g.session}: gateway ${g.status} ${g.paisa}, no order here -> investigate`);

const sum = (xs) => xs.reduce((s, x) => s + x.paisa, 0);
const paidOurs = sum(ours.filter((o) => o.status === "PAID"));
const paidTheirs = sum(report.filter((r) => r.status === "succeeded"));
action.forEach((a) => console.log("-", a));
console.log(`paid total ours ${paidOurs} paisa, gateway ${paidTheirs} paisa, gap ${paidTheirs - paidOurs}`);

৮ · Refund, মেয়াদ শেষ, ব্যর্থ পেমেন্ট আর cash on delivery

Refund আর partial refund. BG-2045-এর ৳১২৫০ থেকে প্রথমে ৳৩০০ ফেরত, তারপর বাকিটা। Admin-এর প্রতিটি refund অনুরোধে নিজের Idempotency-Key, কারণ “Refund” বোতামে দুবার ক্লিক মানে দুবার টাকা ফেরত হওয়া উচিত নয়। আর refund-এর ফলও আসে webhook আর validation API থেকে, অনুরোধের উত্তর থেকে নয়। সত্যিকারের run:

$ curl -X POST …/admin/orders/BG-2045/refunds -H "idempotency-key: rf-BG-2045-a" -d '{"amountPaisa":30000}'
{"refund":"re_0001"}
$ curl … একই key, একই অনুরোধ (দুবার ক্লিক)
{"replay":true,"refund":"re_0001"}
$ curl …/orders/BG-2045
{"ref":"BG-2045","order":"CONFIRMED","payment":"PARTIALLY_REFUNDED","amountPaisa":125000,"refundedPaisa":30000}
$ curl … key rf-BG-2045-b, amountPaisa 100000
{"error":"max refundable 95000 paisa"}
$ curl … key rf-BG-2045-c, amountPaisa 95000
{"refund":"re_0002"}
$ curl …/orders/BG-2045
{"ref":"BG-2045","order":"CONFIRMED","payment":"REFUNDED","amountPaisa":125000,"refundedPaisa":125000}

shop log: evt_0011 refund.succeeded  from=PAID to=PARTIALLY_REFUNDED
shop log: evt_0012 refund.succeeded  from=PARTIALLY_REFUNDED to=REFUNDED

৳১০০০ চাওয়া হয়েছিল, কিন্তু বাকি ছিল মাত্র ৳৯৫০, তাই 422. সীমাটি বাজারঘর আর gateway দুই জায়গাতেই যাচাই হয়। লক্ষ করুন, order-এর অবস্থা CONFIRMED-ই থাকল; টাকা ফেরত মানে order মুছে ফেলা নয়। পণ্য ফেরত এসেছে কি না, stock বাড়বে কি না, তা আলাদা ব্যবসায়িক সিদ্ধান্ত। আর ক্রেতা নিজের ব্যাংকের কাছে লেনদেন নিয়ে আপত্তি তুললে (chargeback বা dispute) সেটি আরেকটি পথ, যার নিয়ম gateway আর ব্যাংক ঠিক করে; এই পর্বে তা আলোচনা করা হয়নি।

মেয়াদ শেষ আর ব্যর্থতা। Session-এর মেয়াদ ল্যাবে ৩ সেকেন্ড করে একজন ক্রেতাকে পাতায় গিয়ে কিছু না করে চলে যেতে দেওয়া হলো। আরেকজন “Fail (test)” চাপলেন:

18:11:31.597 gateway session expired         session=sess_0006
18:11:31.621 shop    payment moved           evt=evt_0013 type=payment.expired from=PENDING to=EXPIRED
{"ref":"BG-2046","order":"CANCELLED","payment":"EXPIRED","amountPaisa":42000,"refundedPaisa":0}
late visit to hosted page: 410

18:11:33.674 shop    payment moved           evt=evt_0014 type=payment.failed from=PENDING to=FAILED
{"ref":"BG-2047","order":"AWAITING_PAYMENT","payment":"FAILED","amountPaisa":125000,"refundedPaisa":0}

দুটির ফল আলাদা রাখা হয়েছে। মেয়াদ শেষ হলে order বাতিল, আর বাস্তবে আটকে রাখা stock ছেড়ে দেওয়া (পর্ব ৪৩-এর reservation-এর মেয়াদ)। ব্যর্থ হলে order বাকিই থাকে, কারণ ক্রেতা হয়তো অন্য কার্ড দিয়ে আবার চেষ্টা করবেন; তখন নতুন payment সারি, নতুন key (pay_BG-2047_2). মেয়াদ পেরোনো পাতায় দেরিতে গেলে gateway 410 Gone দেয়।

Cash on delivery. বাংলাদেশের অনলাইন কেনাকাটায় COD বহুল প্রচলিত বলে ব্যাপকভাবে জানা যায়, যদিও এর সঠিক অনুপাতের নির্ভরযোগ্য সংখ্যা আমরা এখানে দিচ্ছি না। নকশার দিক থেকে COD একই state machine-এর আরেকটি পথ, শুধু খবর দেয় gateway নয়, delivery-র লোক বা courier-এর system. Order শুরুতেই CONFIRMED (পণ্য পাঠানো যাবে), payment PENDING; টাকা হাতে পেলে PAID, ক্রেতা না নিলে FAILED আর order CANCELLED. সত্যিকারের run:

$ curl -X POST …/checkout -d 'sku=ilish-1kg&qty=1&method=COD'
checkout -> http://localhost:47652/orders/BG-2048/view
{"ref":"BG-2048","order":"CONFIRMED","payment":"PENDING","amountPaisa":125000,"refundedPaisa":0}
$ curl -X POST …/admin/orders/BG-2048/cod -d '{"collected":true}'
{"ok":true}
{"ref":"BG-2048","order":"CONFIRMED","payment":"PAID","amountPaisa":125000,"refundedPaisa":0}
$ curl -X POST …/admin/orders/BG-2048/cod -d '{"collected":true}'      # দ্বিতীয়বার
{"error":"not a pending COD"}

COD-এরও reconciliation লাগে: rider-এর হাতে তোলা টাকা আর courier-এর জমা দেওয়া হিসাব মেলানো। বাস্তবে এখানেও অমিল হয়, তাই PAID লেখার সাথে কে, কখন, কোন delivery থেকে লিখলেন, তা audit log-এ রাখা ভালো।

ল্যাবের শেষে database-এর অবস্থা, সত্যিকারের query:

ref      method  order_status      pay_status  amountPaisa  refundedPaisa
BG-2041  ONLINE  CONFIRMED         PAID        250000       0
BG-2042  ONLINE  CONFIRMED         PAID        42000        0
BG-2043  ONLINE  CONFIRMED         PAID        125000       0
BG-2044  ONLINE  CONFIRMED         PAID        84000        0
BG-2045  ONLINE  CONFIRMED         REFUNDED    125000       125000
BG-2046  ONLINE  CANCELLED         EXPIRED     42000        0
BG-2047  ONLINE  AWAITING_PAYMENT  FAILED      125000       0
BG-2048  COD     CONFIRMED         PAID        125000       0

WebhookEvent: events=12 distinct_ids=12      OutboxEvent order.paid: ৫টি (BG-2041 থেকে BG-2045)

Gateway মোট ১৪টি ঘটনা তৈরি করেছিল, দুটি ইচ্ছা করে ফেলা হয়েছে, বাকি ১২টি; duplicate আর retry মিলিয়ে অনুরোধ এসেছিল তার অনেক বেশি, তবু টেবিলে প্রতিটি id একবারই। পাঁচটি online order-এ টাকা এসেছিল, আর outbox-এ order.paid ঠিক পাঁচটি।

৯ · কার্ডের তথ্য, PCI DSS আর secret ছাড়া log

কার্ডের তথ্য রাখবেন না। কার্ড নম্বর, মেয়াদ আর CVV-র মতো তথ্য নিয়ে যে প্রতিষ্ঠান কাজ করে, তাদের জন্য কার্ড কোম্পানিগুলোর গড়া নিরাপত্তা মান PCI DSS, যা PCI Security Standards Council দেখাশোনা করে। মোটা দাগে নিয়ম হলো, আপনার system কার্ডের তথ্য যত কম ছোঁবে, মানার দায়ের পরিধি তত ছোট হয়। Hosted checkout-এ কার্ডের তথ্য দোকানের server-এ আসেই না, তাই অনেক ক্ষেত্রে দায় অনেক হালকা হয় বলে ধরা হয়। তবে ঠিক কোন প্রশ্নপত্র বা যাচাই আপনার জন্য প্রযোজ্য, তা gateway, acquiring ব্যাংক আর মানের সর্বশেষ version ঠিক করে; এটি আইনি বা compliance পরামর্শ নয়। বিস্তারিত তত্ত্ব Cybersecurity কোর্সের standards আর compliance পর্বে। আর মনে রাখুন, hosted পাতা থাকলেও আপনার নিজের পাতা যদি আক্রান্ত হয়ে ক্রেতাকে জাল একটি “gateway” পাতায় পাঠায়, ক্ষতি আপনারই; তাই নিজের পাতার নিরাপত্তা (পর্ব ৫০) এখানেও প্রাসঙ্গিক।

Log-এ secret নয়। Payment-এর log খুব দরকারি, কারণ অভিযোগ এলে প্রথমে log খোঁজা হয়। কিন্তু সেখানে gateway-র key, webhook secret, স্বাক্ষরের header বা ক্রেতার কার্ড-ফোনের পূর্ণ তথ্য থাকা চলবে না। ল্যাবে pino-র redact ব্যবহার করা হয়েছে (redaction, পর্ব ৩১):

export const log = pino({ base: { svc: process.env.SVC ?? 'shop' },
  timestamp: pino.stdTimeFunctions.isoTime,
  formatters: { level: (label) => ({ level: label }) },
  redact: ['headers.authorization', 'headers["x-bazarpay-signature"]'] });

ভালো payment log-এ থাকে: order ref, session id, event id, event type, আগের ও পরের অবস্থা, পরিমাণ (পয়সায়), উৎস (webhook, reconcile, admin), আর একটি request id. এগুলো দিয়ে একটি অভিযোগের পুরো গল্প জোড়া যায়, যেমন ওপরের log-গুলোতে দেখলেন। ব্যর্থ স্বাক্ষরের log-এ শুধু body-র দৈর্ঘ্য রাখা হয়েছে ("len":68), body নয়। সেকশন ৮-এর শেষে একটি জাল webhook পাঠানো হয়েছিল, সত্যিকারের run:

$ curl …/webhooks/bazarpay -H "x-bazarpay-signature: t=$NOW,v1=00ff00ff…" --data-binary '{"id":"evt_9999","type":"payment.succeeded","sessionId":"sess_0006"}'
{"error":"bad signature"} [401]
shop log: {"level":"warn",…,"svc":"shop","len":68,"msg":"webhook signature rejected"}
$ curl …/orders/BG-2046
{"ref":"BG-2046","order":"CANCELLED","payment":"EXPIRED",…}

১০ · AI-এর যুগে payment কোড

Payment-এর কোড AI খুব আত্মবিশ্বাসের সাথে লেখে, আর প্রায়ই এমনভাবে, যা demo-তে কাজ করে কিন্তু টাকা হারায়। কারণ সহজ: হাজার tutorial-এ “success URL-এ order paid করুন” লেখা আছে, কারণ সেটিই সবচেয়ে ছোট উদাহরণ। নিচের ভুলগুলো খুঁজুন।

AI-এর লেখা payment কোড মেলানোর চেকলিস্ট

• Return URL হাতে লিখে status=success দিয়ে খুলেছি, order বদলায়নি
• Form-এ বাড়তি amount পাঠিয়েছি, gateway-তে গেছে catalogue-এর দাম
• একই webhook দুটি সমান্তরাল অনুরোধে পাঠিয়ে database-এ একটি সারি আর একটি outbox কাজ দেখেছি
• Webhook ফেলে দিয়ে reconciliation job চালিয়েছি, payment ঠিক হয়েছে
• Gateway-র নাম, endpoint আর field তাদের অফিসিয়াল docs-এর সাথে মিলিয়েছি, AI-এর কথায় নয়
• Diff আর log-এ কোনো key, secret, স্বাক্ষর বা কার্ডের তথ্য নেই