@nevermined-io/payments
    Preparing search index...

    Class OrdersAPI

    The OrdersAPI class wraps the browser-fiat Orders endpoints. An Order is a merchant-initiated, off-plan charge for an arbitrary amount (the Stripe PaymentIntent analog) that the buyer's browser confirms client-side — no plan, no buyer Nevermined account, no delegation.

    createOrder requires an organization-scoped NVM API key: the API reads the merchant organization from the key's own org tag, so a personal key is refused with BCK.ORDER.0003. Payments.setOrganizationId (the X-Current-Org-Id header) does not substitute for an org-scoped key.

    This client is the merchant's: a Payments instance is always constructed with an NVM API key. The buyer never needs one — the buyer's browser confirms the clientSecret with Stripe.js and can poll GET /api/v1/orders/:id directly, which is why OrdersAPI.getOrder sends no key on that call.

    nvm-monorepo apps/api/src/orders/README.md (epic #3238)

    Hierarchy

    • BasePaymentsAPI
      • OrdersAPI
    Index

    Constructors

    constructor

    Properties

    accountAddress appId? currentOrganizationId environment environmentName heliconeApiKey isBrowserInstance nvmApiKey returnUrl scheme version?

    Methods

    createOrder getAccountAddress getBackendHTTPOptions getEnvironmentName getOrder getOrganizationId getPublicHTTPOptions parseNvmApiKey setOrganizationId getInstance

    Constructors

    Properties

    accountAddress: string
    appId?: string
    currentOrganizationId: string | null
    environment: EnvironmentInfo
    environmentName: EnvironmentName
    heliconeApiKey: string
    isBrowserInstance: boolean = true
    nvmApiKey: string
    returnUrl: string
    scheme: "nvm"
    version?: string

    Backend API version (MAJOR.MINOR) pinned by this instance, set from options.version. When unset, every request defaults to LOCKED_API_VERSION.

    Methods

    • Creates an Order and its PaymentIntent, returning the clientSecret a browser confirms against (POST /api/v1/orders).

      Parameters

      Returns Promise<CreateOrderResult>

      The new Order id, its status and — while payable — the clientSecret.

      This method is oriented to merchants. The NVM API Key must be scoped to an active organization whose Stripe Connect account can receive card payments.

      CreateOrderOptions. currency defaults to 'usd'.

      PaymentsError carrying the backend catalogue code: BCK.ORDER.0001 (invalid request), BCK.ORDER.0003 (not an active organization / over the per-order cap), BCK.ORDER.0007 (idempotency-key conflict), BCK.ORDER.0010 (velocity cap — retryable), BCK.ORDER.0004/0005 (Connect account / PaymentIntent failure, no money moved). A refusal without a catalogue code (e.g. a gateway or throttle response) carries http_<status> instead.

       const { orderId, clientSecret } = await payments.orders.createOrder({
         amountMinor: 3437, // $34.37
         description: 'Cart checkout — 3 items',
         idempotencyKey: 'merchant-order-4821',
       })

    • It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.

      Returns string | undefined

      The account address extracted from the NVM API Key

    • Internal

      Returns the HTTP options required to query the backend.

      Parameters

      • method: string

        HTTP method.

      • Optionalbody: any

        Optional request body.

      • OptionalextraHeaders: Record<string, string>

        Optional per-call header overrides. Use { 'X-Current-Org-Id': orgId } to target a specific workspace for one call without mutating the instance-level pin.

      Returns any

      HTTP options object.

    • Reads the buyer-safe view of an Order by id (GET /api/v1/orders/:id).

      Parameters

      • orderId: string

        The unguessable Order id returned by createOrder.

      Returns Promise<Order>

      The endpoint is anonymous — the unguessable id is the sole access control — so this call sends no API key (the Payments instance still needs one to be constructed). The response never includes the merchant identity or the fee, and carries clientSecret only while the Order is payable.

      Order

      PaymentsError with code BCK.ORDER.0002 when no Order has this id. The read endpoint is rate-limited — all anonymous callers behind one IP share a bucket of 60 requests per minute — and a throttled call carries no catalogue code, so it surfaces as code http_429. That is distinct from the create-side velocity cap BCK.ORDER.0010; poll sparingly and back off on http_429.

       const order = await payments.orders.getOrder(orderId)
       if (order.status === 'paid') fulfil(order)

    • Returns the current organization context applied to every authenticated backend request via the X-Current-Org-Id header.

      null means "no pinned workspace" — the backend falls back to the caller's API-key tag or most-recent active membership.

      Returns string | null

    • Internal

      Get HTTP options for public backend requests (no authorization header). Converts body keys from snake_case to camelCase for consistency.

      Parameters

      • method: string

        HTTP method

      • Optionalbody: any

        Optional request body (keys will be converted to camelCase)

      Returns { body?: string; headers: Record<string, string>; method: string }

      HTTP options object

    • Parses the NVM API Key to extract the account address.

      Returns { accountAddress: string; heliconeApiKey: string }

      PaymentsError if the API key is invalid.

    • Sets the organization context applied to every subsequent authenticated backend request via the X-Current-Org-Id header.

      Pass null to clear the pin and fall back to the backend default.

      Parameters

      • organizationId: string | null

        Org ID (e.g. org-…) or null to clear.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods