@obhco/pay 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# @obhco/pay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Take payments inside your own service with Iranian gateways — **Sadad**,
+**Zarinpal**, **Mellat (Behpardakht)** and **Digipay** — and report every
+payment to OBH for accounting, settlement tracking and reports.
+
+Each service uses **its own gateway terminal and credentials**. Money settles
+straight to the service's account; OBH never touches a bank, it only receives
+the finance reports.
+
+```
+customer ──► your service ──► bank gateway
+                 │  ▲              │
+                 │  └── callback ──┘   (verified server-to-server)
+                 ▼
+               OBH  ◄── signed finance report (payment.snapshot)
+```
+
+Requires Node.js 20+, server-side only. Never ship gateway credentials or the
+OBH service key to a browser.
+
+## Install
+
+```bash
+pnpm add @obhco/pay
+```
+
+## 1. Storage
+
+The package keeps no state of its own. You provide a `PaymentStore`; it needs
+a table and a handful of lookups. `MemoryPaymentStore` is included for tests
+and local development only.
+
+Minimum table (adapt to your database):
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `reference` | text, unique | `PAY-…` id of the attempt |
+| `order_id` | text, indexed | your own order id |
+| `attempt` | int | 1, 2, 3… per order |
+| `gateway` | text | `sadad`, `zarinpal`, … |
+| `gateway_order_id` | text | digits only, unique per gateway |
+| `amount` | text/bigint | whole Rials |
+| `status` | text | `pending` `completed` `failed` `cancelled` `expired` |
+| `environment` | text | `live` or `test` |
+| `provider_session_id` | text, indexed | token / authority / RefId |
+| … | | the remaining fields of `PaymentRecord` |
+
+Implement `PaymentStore` (see `src/store.ts`). The only subtle method is
+`transition(reference, from, patch)`: it must update **only if the stored
+status still equals `from`** and return `null` otherwise (for SQL:
+`UPDATE … WHERE reference = ? AND status = ?` and check the row count). That
+is what stops a double callback from completing a payment twice.
+
+`nextGatewayOrderId(gateway)` must return a digits-only number that is unique
+per gateway; a database sequence is ideal.
+
+## 2. Configure
+
+```ts
+// lib/pay.ts
+import { createPay } from "@obhco/pay"
+import { store } from "./payment-store"
+
+export const pay = createPay({
+  service: "afarin", // short id, same as your OBH service slug
+  baseUrl: "https://afarinai.ir", // your public origin (for bank callbacks)
+  store,
+  // gateways: ["zarinpal", "sadad"],  // default: every gateway with credentials
+  // defaultGateway: "zarinpal",
+})
+```
+
+Gateways are enabled by environment variables in **your** service:
+
+| Gateway | Variables |
+| --- | --- |
+| Sadad | `SADAD_MERCHANT_ID`, `SADAD_TERMINAL_ID`, `SADAD_TERMINAL_KEY` (+ `SADAD_BASE_URL`, `SADAD_RELAY_URL`, `SADAD_RELAY_SECRET` if you call it through an Iranian relay) |
+| Zarinpal | `ZARINPAL_MERCHANT_ID` (`ZARINPAL_SANDBOX=true` for the sandbox) |
+| Mellat | `BEHPARDAKHT_TERMINAL_ID`, `BEHPARDAKHT_USERNAME`, `BEHPARDAKHT_PASSWORD` (+ `BEHPARDAKHT_RELAY_URL`, `BEHPARDAKHT_RELAY_SECRET`, `BEHPARDAKHT_CALLBACK_URL`) |
+| Digipay | `DIGIPAY_USERNAME`, `DIGIPAY_PASSWORD`, and `DIGIPAY_AUTHORIZATION` or `DIGIPAY_CLIENT_ID` + `DIGIPAY_CLIENT_SECRET` (+ `DIGIPAY_BASE_URL`) |
+
+Finance reporting to OBH:
+
+| Variable | Value |
+| --- | --- |
+| `OBH_BASE_URL` | OBH origin, e.g. `https://obhco.ir` |
+| `OBH_SERVICE_KEY` | Service credential (`keyId.secret`) created in OBH → Services |
+| `PAY_ENVIRONMENT` | `test` while using sandbox terminals; default `live` |
+
+If `OBH_BASE_URL` / `OBH_SERVICE_KEY` are missing, payments still work and
+nothing is reported. Check the connection with `await pay.pingObh()`.
+
+## 3. Start a payment
+
+```ts
+// app/api/checkout/route.ts (Next.js)
+import { redirectResponse } from "@obhco/pay"
+import { pay } from "@/lib/pay"
+
+export async function POST(request: Request) {
+  const { orderId, amount, gateway, mobile } = await request.json()
+
+  const { redirect } = await pay.start({
+    orderId, // your order id; one order can have several attempts
+    amount, // whole Rials
+    description: `Order ${orderId}`,
+    gateway, // optional; see pay.listGateways()
+    customerMobile: mobile, // required by Digipay
+    returnUrl: `https://afarinai.ir/orders/${orderId}`,
+  })
+
+  return redirectResponse(redirect) // 303, or an auto-POST form for Mellat
+}
+```
+
+`pay.listGateways()` returns what you can offer at checkout (Persian
+`displayName`, `kind: "card" | "installment"`, `requiresCustomerMobile`).
+
+Starting the same order twice returns the open session instead of creating a
+second one, and an order that is already paid throws `ORDER_ALREADY_PAID`.
+
+## 4. Receive the bank callback
+
+```ts
+// app/api/pay/[gateway]/callback/route.ts
+import { callbackRoute } from "@obhco/pay"
+import { pay } from "@/lib/pay"
+
+async function handle(request: Request, ctx: { params: Promise<{ gateway: string }> }) {
+  const { gateway } = await ctx.params
+  return callbackRoute(pay, gateway, {
+    fallbackUrl: "https://afarinai.ir/checkout",
+  })(request)
+}
+
+export { handle as GET, handle as POST }
+```
+
+The path must match `callbackPath` (default `/api/pay/{gateway}/callback`).
+The handler finds the payment, **verifies it with the bank server-to-server**,
+records the result and sends the customer back to `returnUrl` with
+`?reference=…&status=completed|failed|pending`.
+
+> Never trust that query string. On the page the customer lands on, load the
+> payment with `pay.get(reference)` and fulfil the order only if
+> `status === "completed"`.
+
+## 5. Keep it healthy
+
+Run `pay.reconcile()` every few minutes (cron, queue worker or a protected
+route). It expires abandoned sessions, retries verifications that hit a
+network error, and re-sends any report OBH has not acknowledged:
+
+```ts
+const { expired, reverified, reported } = await pay.reconcile()
+```
+
+Without it, a payment whose callback was lost stays pending, and OBH shows the
+service as **stale** on its reports page.
+
+When the customer comes back and the payment is still pending (the bank's verify
+gave no answer the first time), call `await pay.recheck(reference)` to verify it
+again right away.
+
+## What OBH receives
+
+For every state change the package sends one `payment.snapshot` (the full
+state of one attempt) to `POST {OBH_BASE_URL}/api/v1/finance/events`,
+authenticated with your service key. OBH upserts it by
+`(service, reference)`, so retries and reordering are harmless; a failed
+report never blocks the payment and is re-sent by `reconcile()`.
+
+Sent: reference, order id, attempt, gateway, amount, status, timestamps, trace
+and reference numbers, masked card, installment type (Digipay). **Not sent:**
+customer mobile, return URL, or your `metadata` (opt in with
+`report: { …, includeMetadata: true }`).
+
+OBH then does the rest: accounting and revenue, per-service settlement
+accounts per gateway, installment schedules for Digipay, reconciliation,
+success rates by gateway and service, and stale-service alerts.
+
+## Testing
+
+* Use the gateways' own sandboxes (`ZARINPAL_SANDBOX=true`, bank test
+  terminals) with `PAY_ENVIRONMENT=test`; test payments are kept out of
+  OBH's financial totals.
+* Unit tests can pass a fake adapter in `gateways: [...]` and a
+  `MemoryPaymentStore`; see `tests/pay.test.ts` for a complete example.
+
+## Errors
+
+`PayError.code` is one of `INVALID_REQUEST`, `GATEWAY_NOT_AVAILABLE`,
+`GATEWAY_ERROR`, `ORDER_ALREADY_PAID`, `PAYMENT_NOT_FOUND`, `ORDER_MISMATCH`,
+`INVALID_CALLBACK`, `REPORT_FAILED`. Use `isPayError(error)` to branch on it.
+
+## Security notes
+
+* A callback is only a hint; the result always comes from the bank's verify
+  call, and the verified amount must equal the stored amount (otherwise the
+  payment is failed and flagged, never completed).
+* Payments move `pending → final` exactly once (compare-and-set).
+* Keep gateway credentials and `OBH_SERVICE_KEY` in server environment
+  variables only.

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export type PayErrorCode = "INVALID_REQUEST" | "GATEWAY_NOT_AVAILABLE" | "GATEWAY_ERROR" | "ORDER_ALREADY_PAID" | "PAYMENT_NOT_FOUND" | "ORDER_MISMATCH" | "INVALID_CALLBACK" | "REPORT_FAILED";
+/** Error raised by the package. `code` is stable; `message` is for logs. */
+export declare class PayError extends Error {
+    readonly code: PayErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: PayErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function isPayError(error: unknown): error is PayError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,uBAAuB,GACvB,eAAe,GACf,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,CAAA;AAEnB,4EAA4E;AAC5E,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAGxC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOpC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/** Error raised by the package. `code` is stable; `message` is for logs. */
+export class PayError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "PayError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export function isPayError(error) {
+    return error instanceof PayError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAUA,4EAA4E;AAC5E,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAc;IAClB,OAAO,CAA0B;IAE1C,YACE,IAAkB,EAClB,OAAe,EACf,OAAiC;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,QAAQ,CAAA;AAClC,CAAC"}

package/dist/gateways/digipay.d.ts

@@ -0,0 +1,36 @@
+import { type PaymentGatewayAdapter } from "../types.js";
+export declare const DIGIPAY_PROVIDER_CODE = "digipay";
+export declare const DIGIPAY_PROVIDER_NAME = "Digipay (Installments / BNPL)";
+/**
+ * Purchase `type` values Digipay posts back in the payment result and expects
+ * again on `purchases/verify?type=`.
+ */
+export declare const DIGIPAY_PURCHASE_TYPES: Record<number, string>;
+/** Business error codes from the Digipay UPG guide (HTTP 422 bodies). */
+export declare const DIGIPAY_RESULT_CODES: Record<number, {
+    message: string;
+    retryable: boolean;
+}>;
+export declare function describeDigipayCode(code: number | null | undefined, fallback?: string | null): string;
+export type DigipayConfigStatus = {
+    providerCode: typeof DIGIPAY_PROVIDER_CODE;
+    providerName: typeof DIGIPAY_PROVIDER_NAME;
+    baseUrl: string;
+    liveConfigured: boolean;
+    usernameMasked: string | null;
+    clientIdMasked: string | null;
+};
+export declare function getDigipayConfigStatus(): DigipayConfigStatus;
+/** Test hook: forget the cached OAuth access token. */
+export declare function resetDigipayTokenCache(): void;
+export declare function normalizeIranianMobile(value: string | null | undefined): string | null;
+/**
+ * Digipay keys tickets by `providerId` across the whole merchant account,
+ * which other services share, so OBH's order number alone can clash with an
+ * existing ticket. OBH sends it with an `obh-` prefix and accepts both forms
+ * back.
+ */
+export declare function toDigipayProviderId(gatewayOrderId: string): string;
+export declare function fromDigipayProviderId(value: string | null): string | null;
+export declare const digipayPaymentAdapter: PaymentGatewayAdapter;
+//# sourceMappingURL=digipay.d.ts.map

package/dist/gateways/digipay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digipay.d.ts","sourceRoot":"","sources":["../../src/gateways/digipay.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,qBAAqB,EAG3B,MAAM,aAAa,CAAA;AAEpB,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAC9C,eAAO,MAAM,qBAAqB,kCAAkC,CAAA;AAQpE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMzD,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,MAAM,EACN;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAuCxC,CAAA;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,UAazB;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,OAAO,qBAAqB,CAAA;IAC1C,YAAY,EAAE,OAAO,qBAAqB,CAAA;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,OAAO,CAAA;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAmBD,wBAAgB,sBAAsB,IAAI,mBAAmB,CAa5D;AAoDD,uDAAuD;AACvD,wBAAgB,sBAAsB,SAErC;AAwHD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,iBAmBtE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,UAEzD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,iBAEzD;AAQD,eAAO,MAAM,qBAAqB,EAAE,qBAkVnC,CAAA"}