@faiber/faiber-payment

Gateway administration, payment creation, transaction lookup, daily income, browser callbacks, and payment status pages.

Install

npm install @faiber/faiber-payment

Configure

import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { PaymentApi } from "@faiber/faiber-payment";

const tokens = new MemoryTokenProvider();
const client = new FaiberClient("payment", {
  domains: { payment: process.env.FAIBER_PAYMENT_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
const api = new PaymentApi(client);

const gateways = await api.gateways.list();
const payment = await api.createPayment({
  amount: 4900,
  service_name: "my-service",
  service_model: "order",
  service_id: "order-42",
  queue_name: "my_service_queue",
  callback_url: "https://merchant.example/payment-result",
  idempotency_key: "my-service:order-42",
});

Complete capability

This package exposes 36 registered operations from the payments service. Common workflows have concise methods on api; every registered backend route is also available as a named function on api.operations. Generated operation input, query, response, path, verb, and permission contracts are exported from operations.types.

Browser callback and verification routes are exposed in api.operations; callers should preserve the provider query parameters returned by the payment service.

Authentication and authorization

Use a TokenProvider to forward the signed-in user's Bearer token, or enable withCredentials for secure HttpOnly cookie sessions. Permission requirements copied from service route guards are included in each operation's JSDoc. The SDK does not embed API keys, credentials, localhost URLs, sandbox hosts, or production hosts.

Inputs, queries, responses, and transport

All methods return the complete Axios response, including status, headers, and request IDs. Request bodies and query objects are named exported interfaces. Nested pagination uses keys such as page[number] and page[size] where required by the service. Standard Axios request options, headers, timeouts, adapters, interceptors, and AbortSignal cancellation are supported as the final argument.

Generic REST resources are capability-guarded. Calling a legacy method that the service does not register throws UnsupportedOperationError before sending a request instead of producing a backend 405.

Errors and cancellation

try {
  await api.client.get("/health", undefined, { signal: AbortSignal.timeout(5_000) });
} catch (error) {
  // Axios errors retain response.status and the service error body.
}

Use @faiber/faiber-ts-sdk when one application needs multiple Faiber services with one configuration.

Verified checkout and readiness

operations.gatewaySetupCheckPost() performs a read-only live-provider check with admin:gateway:read. Product-specific payment operations cover 2done, fitness and storefront checkout. Internal endpoints require their product's trusted server credential; an end-user token alone does not grant access.

operations.assetCheckoutReceiptGet(purchaseId, options) accepts x-asset-payment-token through options.headers and returns a raw verified receipt with purchaseId, transaction, integer IRR amount, providerVerified and status (pending, accepted, or rejected). Other product receipt operations retain their service envelopes. Payment creation uses stable product-specific idempotency keys; retry fitness checkout through fitnessRetryPost rather than creating an unrelated transaction.

Gateway and transaction administration

Gateway identifiers are integers. gateways.list({ status: "active", "page[number]": 1, "page[size]": 20 }) returns data.data and data.meta. Gateway create/update supports sandbox; nullable response fields are always present. The options response is opaque stored provider configuration and may contain encrypted values: do not populate editable credential fields from it or log it. Delete returns the removed gateway record, not a boolean result. Gateway calls require the corresponding admin:gateway:read, create, update, or delete permission.

transactions.list() returns a nested data.transactions page, filtered aggregate summaries, service names and gateway options. Transaction records use uuid; they declare no currency field. transactions.show(uuid) and transactionStatus(uuid) return status only. Administration requires admin:transaction:read, and verify/reject requires admin:transaction:verify plus an authenticated verifier. Verification may contact a payment provider; inspect its successful result rather than equating HTTP200 with a successful payment.

gatewayOptions() returns { providers, statuses } label/value arrays. dailyIncomeFor({ days: 7 }) returns UTC date/amount points, including zero dates; the backend clamps the day window to1–90. No count field is returned. createPayment() accepts an optional idempotency_key; trusted product, fitness, Asset and storefront purchases must use their dedicated server-authorized checkout contracts. Generic creation is not an authorization bypass for those purchases.

Payment navigation operations return text/HTML, not JSON envelopes. Provider callbacks accept Authority, transid or paymentNumber in the query for both GET and POST. A callback may return303 with a Location header for a configured allowed HTTPS origin; otherwise it returns the payment result page. In Node, pass maxRedirects: 0 and a validateStatus that accepts303 to inspect that response. A result page with HTTP200 can describe a failed payment. These routes may contact the real provider and are not read-only health checks.

Configured reward-pack checkouts

rewardCheckouts.create(product, body, options) and rewardCheckouts.receipt(product, transactionId, options) require that product's configured backend Bearer credential. The server validates model, order, idempotency key and HTTPS callback origin. These endpoints create/read verified Payment transactions; Asset alone credits a wallet after independently matching the receipt. Pending or cancelled payments never issue coins. Product settings belong in service configuration, and these credentials must stay off clients.

Funded reward refunds

PaymentApi.rewardRefunds exposes list, show, start, confirm, and reopen. These operator calls require IDP authentication and the applicable transaction permission. Writes additionally require assignment to the configured product. The payer cannot verify its own refund. Preserve operation_id and version when retrying an unchanged request; changed semantics or stale rounds return HTTP 409. The methods preserve Axios responses and accept RequestOptions, including an abort signal.

Bank execution takes place in the original merchant portal. Two distinct assigned operators then verify the full refund to the original payer. Reopening a review round never executes another bank refund. rewardCheckout.refund is a trusted backend integration and requires an existing Asset escrow; never expose its service credential in browser code. Readiness reports configuration only.