> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK advanced services

> Use the Node.js SDK server-side Universal Payment Gateway integration and follow the canonical AvraAPI payment guides.

The Node.js SDK supports one Advanced Service: the **Universal Payment Gateway
(UPG)**. Its typed, async `payment()` accessor is for trusted backend payment
work. The canonical UPG documentation defines the full integration, gateway
capabilities, checkout presentation, and authoritative completion rules.

<Warning>
  Payment actions are backend-only. Never send a Project Client Secret,
  `completionContext`, callback artifact, gateway credential, or an unverified
  provider return payload to a browser.
</Warning>

<CardGroup cols={2}>
  <Card title="Quick Setup" icon="bolt" href="/universal-payment-gateway/quick-setup" className="border-2 border-slate-800/60 hover:border-[#0450ff] transition-all duration-700 ease-out">
    Connect a payment flow with the smallest complete backend integration.
  </Card>

  <Card title="Advanced Setup" icon="sliders" href="/universal-payment-gateway/advanced-setup/payment-initiation" className="border-2 border-slate-800/60 hover:border-[#0450ff] transition-all duration-700 ease-out">
    Control initiation, returns, webhooks, and authoritative completion.
  </Card>

  <Card title="Payment Elements" icon="table-columns" href="/universal-payment-gateway/payment-elements/overview" className="border-2 border-slate-800/60 hover:border-[#0450ff] transition-all duration-700 ease-out">
    Add AvraAPI's optional checkout UI while retaining backend authority.
  </Card>

  <Card title="Gateway capabilities" icon="building-columns" href="/universal-payment-gateway/gateway-wise-functions" className="border-2 border-slate-800/60 hover:border-[#0450ff] transition-all duration-700 ease-out">
    Find verified gateway-specific functions, payment choices, and limits.
  </Card>
</CardGroup>

## Access the Node.js payment service

```ts title="Access the Advanced Service" theme={null}
// AvraAPI SDK call. Keep this client in your trusted backend service layer.
const payments = avraapi.payment();
```

The accessor returns a typed `PaymentService`. Lifecycle methods resolve to
dedicated payment value objects rather than generic provider responses.

| Node.js SDK method | Result type | Use it for |
| - | - | - |
| `availability(merchantDomain?)` | `Promise<PaymentAvailability>` | Discover browser-safe payment methods for Payment Elements. |
| `methods(merchantDomain?)` | `Promise<PaymentMethod[]>` | Read the currently usable payment method metadata. |
| `createOrder(CreateOrderOptions)` | `Promise<PaymentSession>` | Prepare one payment session from a backend-owned pending order. |
| `completePayment(PaymentCompletionOptions)` | `Promise<PaymentCompletionResult>` | Verify and complete a callback or return from the backend. |
| `verifyCallback(VerifyCallbackOptions)` | `Promise<VerificationResult>` | Verify a supported callback payload in the server-side flow. |
| `verifySensitiveCallback(SensitiveCallbackOptions)` | `Promise<SensitiveVerificationResult>` | Handle a sensitive callback artifact on the backend only. |

The service also exposes typed gateway facilities through `payHere()`/`payhere()`,
`marxPay()`/`marxpay()`, `onePay()`/`onepay()`, `koko()`, `payPlus()`/`payplus()`,
and `webXPay()`/`webxpay()`. Use the [gateway-wise guides](/universal-payment-gateway/gateway-wise-functions)
for verified provider-specific contracts rather than treating every gateway
alike.

## Keep authority in your backend

<Steps>
  <Step title="Create a pending order">
    Store your order, amount, currency, customer data, and fulfilment intent in
    your application before creating a payment session.
  </Step>

  <Step title="Prepare the session through payment()">
    Use `createOrder()` with a typed `CreateOrderOptions` object. Keep the
    returned `completionContext` with your pending order; it is never browser
    data.
  </Step>

  <Step title="Present the checkout">
    Follow the selected gateway's redirect, overlay, or embedded presentation
    guide. A browser event or return page is not authoritative payment proof.
  </Step>

  <Step title="Complete and fulfil">
    Send the callback or return payload to your backend and use
    `completePayment()`. Fulfil only after the completion result is verified
    and its payment status meets your application policy.
  </Step>
</Steps>

<Info>
  `PaymentSession.completionContext` is deliberately server-only.
  `PaymentCompletionResult` is normalised by AvraAPI, but your application is
  still responsible for idempotency, order state, and the final fulfilment
  decision.
</Info>

## Choose the right UPG guide

<CardGroup cols={3}>
  <Card title="UPG Overview" icon="compass" href="/universal-payment-gateway/overview">
    Learn the lifecycle, project requirements, and supported integration paths.
  </Card>

  <Card title="Webhooks & completion" icon="shield-check" href="/universal-payment-gateway/advanced-setup/webhooks-and-completion">
    Implement authoritative callback verification and reconciliation.
  </Card>

  <Card title="Gateway-wise functions" icon="building-columns" href="/universal-payment-gateway/gateway-wise-functions">
    Use provider-specific capabilities only where they are verified and released.
  </Card>
</CardGroup>

## SDK availability

UPG is available through the PHP, Laravel, and Node.js SDKs. Node.js uses the
released `client.payment()` typed, async server-only lifecycle. Use canonical
UPG guides instead of recreating payment operations through a raw HTTP call.

## Next steps

<CardGroup cols={2}>
  <Card title="Start Quick Setup" icon="rocket" href="/universal-payment-gateway/quick-setup">
    Build the smallest complete payment flow first.
  </Card>

  <Card title="Review UPG errors" icon="triangle-exclamation" href="/universal-payment-gateway/errors">
    Understand safe handling for unavailable methods, callbacks, and completion outcomes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.