neplextech/payments-sdk/payments-sdk-provider-authoring

Payments SDK Provider Authoring

Build providers as independently publishable packages. Keep gateway-specific behavior inside the provider and leave orchestration, lifecycle, persistence, and application infrastructure outside the SDK runtime.

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
• Provider authoring guide:

https://payments.neplex.dev/docs/guides/provider-authoring

• Core package: packages/core
• Existing examples: packages/esewa, packages/fonepay, packages/khalti

Read the provider-authoring guide and the closest existing provider before implementing. Do not copy gateway assumptions between providers.

Protocol boundary

Implement a structural PaymentProvider with a literal provider ID and only the capabilities the gateway actually supports:

import type {
  CheckoutContext,
  CheckoutResult,
  PaymentProvider,
} from '@payments-sdk/core';
export function acmePay(): PaymentProvider<'acme-pay'> {
  return {
    id: 'acme-pay',
    checkout: async (
      context: CheckoutContext<CheckoutOptions>,
    ): Promise<CheckoutResult<'acme-pay'>> => {
      // gateway request and normalized action
    },
  };
}

Use type-only imports from @payments-sdk/core. Provider runtime code must not import core at runtime. Runtime errors and crypto utilities may come from @payments-sdk/payments where appropriate.

Provider implementation

• Inject all I/O through the runtime context fetch and now functions.
• Keep credentials in options and server-side; never read global

environment variables inside the provider.

• Convert application minor units to gateway units at the provider

boundary and document rounding rules.

• Return a normalized redirect, form, or QR action while preserving

gateway-specific data in providerData.

• Map documented statuses conservatively; missing or unknown values

must never become succeeded.

• Parse browser returns as input, not settlement. Implement webhooks

only when the gateway contract and protocol support them.

• Keep signing field order, encoding, endpoint defaults, and response

validation explicit and tested.

Package and test shape

Create a package with:

packages/<provider>/src/index.ts
packages/<provider>/src/checkout.ts
packages/<provider>/src/verify.ts
packages/<provider>/README.md
packages/<provider>/package.json

Add @payments-sdk/payments as a runtime dependency and @payments-sdk/core as a type-only development dependency. Use files: dist and ESM exports matching the existing packages.

Test successful and invalid gateway responses, signature or canonicalization rules, amount conversion, status mapping, missing fields, and provider errors. Add a test that scans built JavaScript and rejects runtime imports of @payments-sdk/core.

Add type-level coverage proving the provider's literal ID, provider options, result data, and capability namespaces flow through @payments-sdk/payments. Prove that a fake provider can be configured without editing packages/sdk runtime source.

Documentation and release

Document installation, credentials, sandbox/production endpoints, options, actions, verification, returns, capabilities, and security caveats. Never invent gateway behavior or production claims.

Run the full workspace checks and inspect the pnpm-packed tarball. Confirm the provider tarball contains no tests, fixtures, secrets, source files, or invalid workspace protocol dependencies.

Do not add provider names or registries to @payments-sdk/payments. Do not modify runtime source to accommodate a provider-specific feature.