@ermis-network/payment-sdk

Server-only CommonJS SDK for integrating a Node.js backend with Ermis Centralized Payment Service. It owns authentication headers, response validation, bounded retries, idempotency keys, webhook verification, and typed errors.

This package requires Node.js 22 or newer. It supports require('@ermis-network/payment-sdk') and NestJS applications compiled with TypeScript module: "commonjs". Do not import it in browser or client-side bundles: payment credentials and webhook secrets must remain on the backend.

Install and configure

npm install @ermis-network/payment-sdk

PAYMENT_SERVICE_URL=https://payment.ermis.network
PAYMENT_CLIENT_ID=your-client-id
PAYMENT_SECRET_KEY=your-secret-key
PAYMENT_WEBHOOK_SECRET=your-webhook-secret

PAYMENT_WEBHOOK_SECRET is needed only by webhook registration. API calls require the other three variables.

API client

import { PaymentGatewayClient } from '@ermis-network/payment-sdk'

const payment = PaymentGatewayClient.fromEnv({
  defaultSuccessUrl: 'https://app.example.com/payment/success',
  defaultCancelUrl: 'https://app.example.com/payment/cancel',
})

const plans = await payment.getPlans()

const checkout = await payment.createCheckout({
  userId: 'user-123',
  email: '[email protected]',
  plan: 'premium-monthly',
})
// Redirect the user to checkout.url.

const portal = await payment.createPortal({ userId: 'user-123' })
// Redirect the user to portal.url.

const subscription = await payment.getSubscription({ userId: 'user-123' })

Checkout and portal calls create and reuse an idempotency key automatically. To reuse a key across application-level retries, pass { idempotencyKey: 'your-stable-key' } as the second argument.

One-time subscription charge

const charge = await payment.createCharge({
  userId: 'user-123',
  amount: 3500,
  description: 'Stream usage for August 2026: 350 minutes',
  effectiveFrom: 'next_billing_period',
}, {
  idempotencyKey: 'usage:user-123:2026-08',
})

ChargeEffectiveFrom is a billing mode, not a timestamp, and it is required with no default. Use next_billing_period for periodic pay-per-minute usage so Paddle adds the charge to the next subscription renewal. Use immediately for an out-of-cycle or final settlement, especially when no next renewal is expected.

Persist one idempotency key for each logical charge and reuse that exact key on retries. The SDK deliberately never generates one for createCharge.

When a renewal fails, every scheduled charge linked to that transaction is reported as charge.payment_failed. A later successful payment can move those charges to charge.paid, so handlers must support the failed-to-paid recovery path.

Express webhook

Install your preferred Redis client and create the deduplication store. The SDK has no hard Redis dependency.

import express from 'express'
import { registerExpressPaymentWebhook } from '@ermis-network/payment-sdk/express'
import { redisWebhookStore } from '@ermis-network/payment-sdk/redis'

const app = express()
const store = redisWebhookStore(redis)

registerExpressPaymentWebhook(app, {
  secret: process.env.PAYMENT_WEBHOOK_SECRET!,
  store,
  handlers: {
    async subscriptionActivated(event) {
      await users.activatePlan(event.userId, event.subscription)
    },
    async subscriptionUpdated(event) {
      await users.updatePlan(event.userId, event.subscription)
    },
    async subscriptionCanceled(event) {
      await users.cancelPlan(event.userId, event.subscription)
    },
    async chargePaid(event) {
      await billing.recordPaidCharge(event.userId, event.charge)
    },
    async chargePaymentFailed(event) {
      await billing.recordFailedCharge(event.userId, event.charge)
    },
  },
})

// Register global JSON parsing only after the payment webhook route.
app.use(express.json())

The default route is /api/v1/payment-callback. Pass path to override it. The adapter verifies raw request bytes, claims the event ID, calls exactly one typed handler, completes successful events, and releases failed events for retry.

Charge handlers are optional for source compatibility, but deliberately fail closed at runtime: an omitted handler returns 500 for its charge event so the gateway retries instead of losing the payment result.

Fastify webhook

import { registerFastifyPaymentWebhook } from '@ermis-network/payment-sdk/fastify'
import { redisWebhookStore } from '@ermis-network/payment-sdk/redis'

await registerFastifyPaymentWebhook(app, {
  secret: process.env.PAYMENT_WEBHOOK_SECRET!,
  store: redisWebhookStore(redis),
  handlers: {
    subscriptionActivated: event => users.activatePlan(event.userId, event.subscription),
    subscriptionUpdated: event => users.updatePlan(event.userId, event.subscription),
    subscriptionCanceled: event => users.cancelPlan(event.userId, event.subscription),
    chargePaid: event => billing.recordPaidCharge(event.userId, event.charge),
    chargePaymentFailed: event => billing.recordFailedCharge(event.userId, event.charge),
  },
})

The Fastify adapter installs a scoped buffer parser, leaving the application's global JSON parser unchanged.

Errors

All SDK failures extend PaymentError and expose stable diagnostics:

import { PaymentError } from '@ermis-network/payment-sdk'

try {
  await payment.getPlans()
} catch (error) {
  if (error instanceof PaymentError) {
    console.error(error.code, error.httpStatus, error.requestId, error.retryable)
  }
}

Credentials are redacted before optional request/response logging hooks run. Generated OpenAPI wire types are internal and are not exported by the package root.