Building

Gateways & installments

OBH offers more than one payment gateway. Call listGateways() to show them on your checkout page, then pass the customer's choice to startPayment(). Requires @obhco/payments 0.2.0.

Available gateways

Code	Kind	What the customer does
`sadad`	`card` (default)	Pays the full amount with any Shetab bank card through Sadad (Bank Melli Iran).
`zarinpal`	`card`	Pays the full amount with any Shetab bank card through Zarinpal. Minimum 10,000 R.
`mellat`	`card`	Pays the full amount with any Shetab bank card through Bank Mellat (Behpardakht).
`digipay`	`installment`	Buys now and pays later in installments with Digipay credit (BNPL), or pays with a Digipay wallet or card. Requires the customer's mobile number.

Do not hard-code this list

OBH lists only the gateways that are currently enabled. A gateway without LIVE credentials disappears from the live list, and new gateways appear without an SDK change.

List gateways

1class OBHPayments {2  listGateways(options?: { simulator?: boolean }): Promise<PaymentGateway[]>3}

GET/api/v1/gateways?simulator=false

Property	Type	Description
coderequired	`"sadad" \| "zarinpal" \| "mellat" \| "digipay" \| string`	Pass this to startPayment as gateway.
displayNamerequired	`string`	Persian label ready for a checkout page, e.g. خرید اقساطی با دیجی‌پی.
kindrequired	`"card" \| "installment"`	Use it to group or label options.
requiresCustomerMobilerequired	`boolean`	When true, collect the customer's mobile number and pass customerMobile.
isDefaultrequired	`boolean`	The gateway used when you omit gateway.
minAmountrequired	`string \| null`	Minimum whole Rial amount, or null when there is none.

Responsejson

1{2  "data": [3    {4      "code": "sadad",5      "name": "Sadad (Bank Melli Iran)",6      "displayName": "پرداخت با کارت بانکی (سداد)",7      "kind": "card",8      "requiresCustomerMobile": false,9      "minAmount": null,10      "isDefault": true,11      "environment": "live"12    },13    {14      "code": "zarinpal",15      "name": "Zarinpal",16      "displayName": "پرداخت با زرین‌پال",17      "kind": "card",18      "requiresCustomerMobile": false,19      "minAmount": "10000",20      "isDefault": false,21      "environment": "live"22    },23    {24      "code": "mellat",25      "name": "Mellat (Behpardakht)",26      "displayName": "پرداخت با کارت بانکی (به‌پرداخت ملت)",27      "kind": "card",28      "requiresCustomerMobile": false,29      "minAmount": null,30      "isDefault": false,31      "environment": "live"32    },33    {34      "code": "digipay",35      "name": "Digipay (Installments / BNPL)",36      "displayName": "خرید اقساطی با دیجی‌پی",37      "kind": "installment",38      "requiresCustomerMobile": true,39      "minAmount": null,40      "isDefault": false,41      "environment": "live"42    }43  ]44}

Build a checkout picker

Load the gateways on your server

1const gateways = await obh.listGateways()

Let the customer choose

Render one option per gateway using displayName. If the chosen gateway has requiresCustomerMobile, ask for the customer's mobile number.

Start the payment with that gateway

app/actions/checkout.tsts

1"use server"2 3import { redirect } from "next/navigation"4 5import { obh } from "@/lib/obh"6 7export async function checkout(form: FormData) {8  const gateways = await obh.listGateways()9  const chosen = gateways.find((g) => g.code === form.get("gateway"))10  if (!chosen) throw new Error("Unknown gateway")11 12  const payment = await obh.startPayment({13    externalOrderId: String(form.get("orderId")),14    amount: "15000000",15    description: "Pro subscription (yearly)",16    gateway: chosen.code,17    customerMobile: chosen.requiresCustomerMobile18      ? String(form.get("mobile"))19      : undefined,20    idempotencyKey: `order-${form.get("orderId")}-${chosen.code}`,21  })22 23  redirect(payment.checkoutUrl!)24}

Verify the return the same way as always

verifyReturn() and getPayment() work for every gateway. Trust only payment.status. payment.gateway tells you which gateway processed the payment.

A new gateway is a new request

The gateway and mobile number are part of the idempotency fingerprint. If the customer switches gateway, use a new idempotency key (for example, include the gateway code). Reusing the old key returns 409 IDEMPOTENCY_CONFLICT.

Digipay installments

With Digipay the customer pays the first installment at checkout and the rest later. For your service nothing changes: once Digipay verifies the purchase, the payment is completed for the full amount, and you can fulfil the order immediately. Digipay owes the remaining installments to OBH, not your customer to you.

customerMobile is required. 09…, +989… and 989… forms are accepted.
Receipt fields map to Digipay values: referenceNumber is the Digipay trackingCode and orderNumber is the providerId.
A customer may also choose a Digipay wallet or card on Digipay's page. Those are full payments, but the result looks the same to you.

Testing with the simulator

With simulator: true, listGateways() returns every gateway, and Digipay payments open the OBH Digipay simulator at /pay/digipay/<ticket>. There you can simulate a BNPL, credit, wallet or card purchase, or a failure. Zarinpal payments open /pay/zarinpal/<authority> and Mellat payments open /pay/mellat/<refId>.

Errors

Code	Meaning
`INVALID_ARGUMENT`	The SDK rejected a malformed `gateway` or `customerMobile` before calling the API.
`GATEWAY_NOT_SUPPORTED`	422 — the gateway code is not one OBH offers.
`CUSTOMER_MOBILE_REQUIRED`	422 — the gateway needs the customer's mobile number.
`GATEWAY_NOT_AVAILABLE`	503 — the gateway is not enabled for LIVE payments. Offer another one from `listGateways()`.

Everything else behaves as described in Create a payment and Errors.