npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@wtree/payload-ecommerce-ngenius

v3.89.2

Published

N-Genius payment adapter for the Payload CMS Ecommerce plugin

Readme

@wtree/payload-ecommerce-ngenius

N-Genius payment adapter for the Payload CMS Ecommerce plugin.

This package implements the ecommerce PaymentAdapter contract. initiatePayment creates a pending transaction and an N-Genius order. confirmOrder verifies the retrieved gateway order before creating a Payload order. N-Genius webhook payloads are not signed. The host configures a custom header in the N-Genius portal, and this adapter compares that header with webhookSecret. The host application supplies apiKey, outletRef, and webhookSecret. This package does not read environment variables.

Installation

npm install @wtree/payload-ecommerce-ngenius

Peer dependencies: payload and @payloadcms/plugin-ecommerce.

Server

import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { ngeniusAdapter } from '@wtree/payload-ecommerce-ngenius'

ecommercePlugin({
  payments: {
    paymentMethods: [
      ngeniusAdapter({
        apiKey: process.env.NGENIUS_API_KEY!,
        outletRef: process.env.NGENIUS_OUTLET_REF!,
        // "sandbox" or "production". The package does not read this from the environment.
        environment: 'sandbox',
        serverURL: process.env.NGENIUS_PUBLIC_SERVER_URL || process.env.NEXT_PUBLIC_SERVER_URL,
        webhookSecret: process.env.NGENIUS_WEBHOOK_SECRET,
        webhookSecretHeader: 'X-Webhook-Secret',
        label: 'Card',
      }),
    ],
  },
})

The ecommerce plugin registers:

  • POST /api/payments/ngenius/initiate
  • POST /api/payments/ngenius/confirm-order
  • POST /api/payments/ngenius/webhook
  • GET /api/payments/ngenius/return

initiatePayment validates the cart, creates a pending transactions document, and creates an N-Genius order with action PURCHASE. When serverURL is set, the create-order body includes merchantAttributes.redirectUrl, cancelUrl, skipConfirmationPage, and cancelText. The gateway reference is stored on ngenius.orderReference. The hosted page URL comes from _links.payment.href. It returns { message, orderReference, paymentPageUrl }. A signed-in purchase without a shipping phone is rejected before that gateway order is created.

GET /api/payments/ngenius/return reads ref or outcome=cancelled and calls finalizeNgeniusPayment. It redirects to {storefrontURL}/checkout/confirm-order?order={id}&success=true only after that finalizer succeeds. storefrontURL is the customer-facing shop origin. serverURL stays the callback origin N-Genius calls. When storefrontURL is set, success and the failed, pending, cancelled, and error checkout redirects all use that shop origin so the browser returns to the cart the customer started with. success=true only tells the confirm-order page to open the existing dialog. It is not proof of payment. Failed, pending, cancelled, and verification errors redirect to /checkout?payment=failed|pending|cancelled|error.

Local sandbox

N-Genius Hosted Checkout requires a publicly reachable HTTPS callback URL. This package does not choose that host. The host passes it as serverURL.

Electrofit keeps the shop on NEXT_PUBLIC_SERVER_URL and passes NGENIUS_PUBLIC_SERVER_URL into the adapter. When the N-Genius variable is empty, the adapter receives the application origin.

Local:

# Terminal 1
bun run dev
# Application: http://localhost:3000

# Terminal 2
ngrok http 3000
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NGENIUS_ENVIRONMENT=sandbox
NGENIUS_PUBLIC_SERVER_URL=https://<current-ngrok-domain>

Electrofit reads NGENIUS_ENVIRONMENT. Leave it unset or set sandbox locally. A production deployment sets production and supplies that environment's API key, outlet reference, and webhook secret together. Any other value is rejected. The shop URL does not select the gateway. Sandbox calls https://api-gateway.sandbox.ngenius-payments.com. Production calls https://api-gateway.ngenius-payments.com. Authentication, order creation, and order retrieval all use the selected host. An explicit production environment cannot be paired with the sandbox API base URL.

Set NGENIUS_DEBUG=true to log request timing for each N-Genius call: label, method, host, status, and elapsed time. Electrofit passes it to the adapter as debug. The logs never include API keys, tokens, or request or response bodies. Leave it unset in normal operation.

The customer continues using http://localhost:3000. Create Order then sends:

  • redirectUrl: https://<current-ngrok-domain>/api/payments/ngenius/return
  • cancelUrl: https://<current-ngrok-domain>/api/payments/ngenius/return?outcome=cancelled

Production uses the public site origin for both variables, for example https://electrofit.ae. Do not commit a real temporary ngrok host.

confirmOrder loads that transaction by ngenius.orderReference and calls finalizeNgeniusPayment. The finalizer retrieves the N-Genius order and creates a Payload order only when the outlet, reference, PURCHASE action, currency, and minor-unit amount match and the payment state is PURCHASED. STARTED, AWAIT_3DS, AUTHORISED, and CAPTURED stay pending. FAILED sets ngenius.state to failed and status to failed. It returns { message, orderID, transactionID }. If that order was already finalized, it returns the existing order instead of creating another.

Webhook

POST /api/payments/ngenius/webhook

This package does not register the webhook URL with N-Genius. In the portal for that same environment, set:

  • Local: https://<current-ngrok-host>/api/payments/ngenius/webhook
  • Production: https://<public-https-origin>/api/payments/ngenius/webhook

Use the webhook secret configured for that environment. N-Genius does not sign webhook bodies. Set a custom header:

  • Header key: X-Webhook-Secret, unless webhookSecretHeader is set to another name
  • Header value: the same string passed as webhookSecret

Requests without that header, or with a different value, are rejected. If webhookSecret is omitted, the endpoint rejects every webhook instead of accepting it unauthenticated.

The webhook authenticates the custom header, then calls the same finalizeNgeniusPayment function as confirmOrder. Payment success is taken from the retrieved gateway order, not from the webhook body alone. A purchase is completed only when that order's outlet, reference, PURCHASE action, currency, and minor-unit amount match the transaction and the payment state is PURCHASED. FAILED sets ngenius.state to failed and status to failed. STARTED, AWAIT_3DS, AUTHORISED, and CAPTURED stay pending and do not create an order.

The ngenius group does not store eventId. Finalization takes a Postgres advisory lock on the N-Genius order reference. If order is already set and status is succeeded, another webhook or confirm call returns that order and does not create a second one.

Client

import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client/react'
import { ngeniusAdapterClient } from '@wtree/payload-ecommerce-ngenius'

<EcommerceProvider
  paymentMethods={[
    ngeniusAdapterClient({
      label: 'Card',
    }),
  ]}
>
  {children}
</EcommerceProvider>

Transaction group

The adapter adds a ngenius group on transactions, shown when paymentMethod is ngenius:

  • orderReference
  • state: pending, captured, or failed