neplextech/payments-sdk/payments-sdk-integration

Payments SDK Integration

Integrate the runtime as an application-owned payment boundary. Keep transport, persistence, HTTP routing, settlement, and fulfillment in the host application.

Canonical references

• Documentation: https://payments.neplex.dev
• Agent index: https://payments.neplex.dev/llms.txt
• Full agent documentation: https://payments.neplex.dev/llms-full.txt
• Installation: https://payments.neplex.dev/docs/installation
• Quick start: https://payments.neplex.dev/docs/quick-start
• Provider docs: https://payments.neplex.dev/docs/providers

Read the provider-specific page before configuring gateway options. Provider contracts and gateway details can vary.

Install and configure

Install the scoped runtime and only the providers the application uses:

pnpm add @payments-sdk/payments @payments-sdk/esewa
pnpm add @payments-sdk/payments @payments-sdk/fonepay
pnpm add @payments-sdk/payments @payments-sdk/khalti

Create one configured runtime:

import { createPayments } from '@payments-sdk/payments';
import { fonepay } from '@payments-sdk/fonepay';
const payments = createPayments({
  providers: [
    fonepay({
      merchantCode: process.env.FONEPAY_MERCHANT_CODE!,
      secretKey: process.env.FONEPAY_SECRET_KEY!,
      fonepayBaseUrl: process.env.FONEPAY_BASE_URL!,
    }),
  ],
});

Provider IDs, provider options, result data, and capability namespaces are inferred from the providers array.

Checkout and verification

Use integer minor units for amount. A checkout result is an action for the application to render or execute:

const checkout = await payments.checkout({
  provider: 'fonepay',
  amount: 1500_00,
  currency: 'NPR',
  reference: 'order_123',
  providerOptions: {
    returnUrl: 'https://merchant.example/payments/fonepay/return',
    remarks1: 'Payment for order 123',
  },
});

FonePay Dynamic QR is selected with mode: 'dynamic_qr'. Configure the provider's API username and password, then render the returned qr payload and retain the PRN for polling:

const qr = await payments.checkout({
  provider: 'fonepay',
  amount: 350_00,
  currency: 'NPR',
  reference: 'order_123',
  providerOptions: {
    mode: 'dynamic_qr',
    remarks1: 'Payment for order 123',
  },
});
const status = await payments.verify({
  provider: 'fonepay',
  reference: 'order_123',
  providerOptions: { amount: 350_00 },
});

Verify according to the provider's gateway flow. For FonePay Dynamic QR, poll the PRN status endpoint through payments.verify. For hosted checkout, pass the raw browser return to its signed returns capability:

const returned = await payments.returns.fonepay(request);

The provider checks FonePay's HMAC signature and merchant code. The application still owns reference matching, persistence, idempotency, and fulfillment.

Capability boundaries

• eSewa implements checkout, verify, and signed browser returns.
• FonePay implements signed hosted checkout, Dynamic QR checkout with

PRN verification, and signed browser returns.

• Khalti implements redirect checkout, lookup verification, and

browser return parsing; callback status is not authoritative.

• The initial providers do not implement webhooks, refunds, or

cancellations.

Keep route registration, raw request handling, persistence, retries, idempotency, settlement transactions, and fulfillment in the application. Pass injected fetch and now when tests or application observability require control.

Never expose provider credentials to browser code or logs. Do not claim success from a redirect, QR display, or callback without verification.