@wtree/payload-ecommerce-ngenius
v3.89.2
Published
N-Genius payment adapter for the Payload CMS Ecommerce plugin
Maintainers
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-ngeniusPeer 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/initiatePOST /api/payments/ngenius/confirm-orderPOST /api/payments/ngenius/webhookGET /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 3000NEXT_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/returncancelUrl: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, unlesswebhookSecretHeaderis 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:
orderReferencestate:pending,captured, orfailed
