Introduction

@payments-sdk/payments gives applications one configured interface for provider checkout, verification, and returns while leaving HTTP routes, persistence, and settlement in the application.

Install for Agents

npx skills add neplextech/payments-sdk

Agents can load the project index at https://payments.neplex.dev/llms.txt or the full reference at https://payments.neplex.dev/llms-full.txt.

The boundary

The runtime does not know which providers exist. Install the provider packages you need and pass their instances to createPayments():

import { fonepay } from '@payments-sdk/fonepay';
import { createPayments } from '@payments-sdk/payments';

const payments = createPayments({
  providers: [
    fonepay({
      merchantCode,
      secretKey,
      fonepayBaseUrl,
    }),
  ],
});

The configured provider IDs and capabilities drive the resulting TypeScript surface. A provider that does not implement returns or webhooks does not add those namespaces to the inferred runtime.

Start here

What the runtime owns

@payments-sdk/payments validates normalized payment inputs, selects a configured provider, supplies the runtime fetch and clock, and returns normalized actions and statuses. It does not create HTTP routes, store payment records, or decide when an order is fulfilled.

The application owns those boundaries. A typical flow is:

1. Create an application payment record and a payment intent.
2. Call payments.checkout() and execute the returned action in the browser.
3. Accept the provider's return or webhook in an application route.
4. Call the provider's returns or verification capability as its gateway contract requires.
5. Persist settlement idempotently and fulfill the order.

Important distinction

A browser return is a request to parse, not a replacement for application reconciliation. Validate the provider's signature where supported, match the reference to the stored intent, and make the final state change idempotent in your application's persistence boundary.