Node, PHP and Python libraries

The official libraries wrap the API with typed objects, automatic idempotency and retries, cursor pagination and webhook verification. None of them has a runtime dependency.

Install

yarn add @bezanbecard/node

Create a client

The key decides the mode: sk_test_… sees only test data, sk_live_… only live data. Keep it on your server.

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

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

Methods

The resources and methods are the same in all three. The table names them as Node does: PHP calls the same names with -> ($bezanbecard->payments->attachDeposit(…)) and lists with all and deletes with delete; Python spells every name in snake_case (bezanbecard.payment_links.list(), attach_deposit) and deletes with delete.

Create and confirm a payment

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);

Errors

Every library raises one class per error type, carrying type, code, param, message and the request id.

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;
}

The codes are listed in errors.

Retries, idempotency and webhooks

• Every POST carries an Idempotency-Key, reused on retries. Network failures, 409 idempotency conflicts, 429 and 5xx are retried twice by default with a growing, jittered wait that respects Retry-After. Pass your own key to stay idempotent across restarts (idempotency).
• Lists iterate every page for you (pagination).
• constructEvent / Webhook::constructEvent / Webhook.construct_event verify the signature on the raw body and accept either v1 during a secret roll (webhooks).

Configuration

Per-request options (a different key, an idempotency key, a version) go in the last argument of each method, so one process can act for several accounts.