کتابخانه‌های Node، PHP و Python

کتابخانه‌های رسمی API را با شیءهای نوع‌دار، درخواست تکرارپذیر و تلاش دوبارهٔ خودکار، صفحه‌بندی با نشانگر و بررسی وب‌هوک می‌پوشانند. هیچ‌کدام وابستگی زمان اجرا ندارند.

نصب

yarn add @bezanbecard/node

ساخت کلاینت

حالت از روی کلید معلوم می‌شود: sk_test_… فقط دادهٔ آزمایشی را می‌بیند و sk_live_… فقط دادهٔ واقعی را. کلید را روی سرور نگه دارید.

import Bezanbecard from '@bezanbecard/node';
// CommonJS: const { Bezanbecard } = require('@bezanbecard/node');

const bezanbecard = new Bezanbecard(process.env.BEZANBECARD_SECRET_KEY);

متدها

منابع و متدها در هر سه کتابخانه یکی‌اند. جدول نام‌ها را به شیوهٔ Node آورده است: PHP همین نام‌ها را با -> صدا می‌زند ($bezanbecard->payments->attachDeposit(…))، برای فهرست all و برای حذف delete دارد؛ Python همهٔ نام‌ها را به شکل snake_case می‌نویسد (bezanbecard.payment_links.list()، attach_deposit) و برای حذف delete دارد.

ساخت و تأیید پرداخت

const payment = await bezanbecard.payments.create({
  amount: 12_500_000,
  reference: 'order-1042',
  customer_details: { name: 'Test Customer', phone: '09900001234' },
  return_url: 'https://shop.example/orders/1042/thanks',
});
// redirect to payment.checkout_url; later:
const current = await bezanbecard.payments.retrieve(payment.id);
if (current.status === 'succeeded') fulfilOrder(current.reference);

خطاها

هر کتابخانه برای هر نوع خطا یک کلاس دارد که type، code، param، message و شناسهٔ درخواست را نگه می‌دارد.

import { InvalidRequestError } from '@bezanbecard/node';

try {
  await bezanbecard.payments.create({ amount: 500 });
} catch (error) {
  if (error instanceof InvalidRequestError && error.code === 'amount_too_small') console.log(error.param, error.requestId);
  else throw error;
}

فهرست کدها در خطاها آمده است.

تلاش دوباره، درخواست تکرارپذیر و وب‌هوک

• هر POST یک Idempotency-Key دارد که در تلاش‌های دوباره هم همان می‌ماند. خطای شبکه، تداخل 409، 429 و 5xx به‌طور پیش‌فرض دو بار با فاصلهٔ رو به افزایش و تصادفی دوباره امتحان می‌شوند و Retry-After رعایت می‌شود. برای تکرارپذیر ماندن بعد از راه‌اندازی دوباره، کلید خودتان را بدهید (درخواست تکرارپذیر).
• فهرست‌ها همهٔ صفحه‌ها را برایتان مرور می‌کنند (صفحه‌بندی).
• constructEvent / Webhook::constructEvent / Webhook.construct_event امضا را روی بدنهٔ خام بررسی می‌کنند و هنگام تعویض کلید هر کدام از دو v1 را می‌پذیرند (وب‌هوک‌ها).

پیکربندی

گزینه‌های هر درخواست (کلیدی دیگر، کلید تکرارپذیری، نسخه) در آخرین آرگومان هر متد می‌آیند؛ پس یک فرایند می‌تواند برای چند حساب کار کند.