@lmnto/geidea-payment

Node module for Geidea Checkout v2 (HPP) APIs.

Installation

npm i @lmnto/geidea-payment

Local testing

cp .env.example .env
# Edit .env with your Geidea sandbox credentials
npm install
npm run example:create-session

See example/README.md for all example scripts and the HPP test page.

Import package

const geidea = require('@lmnto/geidea-payment');

Initialize provider instance

const config = {
	REGION: 'AE', // EG | KSA | SA | AE | UAE
	MERCHANT_PUBLIC_KEY: '',
	API_PASSWORD: '',
	CURRENCY_LABEL: 'AED',
	CALLBACK_URL: 'https://your-domain.com/webhooks/geidea',
	LANGUAGE: 'en',
	// Optional override:
	// API_BASE_URL: 'https://api.geidea.ae',
};
const provider = geidea.Init(config);

Create a checkout session

Geidea Checkout v2 requires amount, currency, timestamp, signature, and callbackUrl when creating a session. 3D Secure is handled by the hosted payment page.

const data = await provider.createSession({
	amount: 19.99,
	currency: 'AED',
	merchantReferenceId: 'your-order-id',
	returnUrl: 'https://your-domain.com/payment/return',
});
// data.session.id is used with GeideaCheckout JS: payment.startPayment(sessionId)

Initiate checkout (mastercard-payment compatible shape)

const order = {
	id: 'ADBCed12345',
	reference: 'ADBCed12345',
	currency: 'AED',
	amount: '19.99',
};
const customer = {
	email: '[email protected]',
	mobilePhone: '97158948940',
	firstName: 'Test',
	lastName: 'User',
};
const interaction = {
	returnUrl: 'https://your-domain.com/payment/success',
	callbackUrl: 'https://your-domain.com/webhooks/geidea',
	language: 'en',
};
const data = await provider.initiateCheckout(order, customer, interaction);

Retrieve order details

// By merchant reference (same id used at create-session)
const orderByRef = await provider.retrieveOrderByMerchantReference('your-order-id');

// By payment intent + order ID
const orderDetails = await provider.retrieveOrder(paymentIntentId, orderId);

Validate callback signature

const isValid = provider.validateCallbackSignature(callbackPayload);

Frontend helpers

const scriptUrl = provider.getCheckoutScriptUrl();
const checkoutUrl = provider.getCheckoutPageUrl(sessionId);

Environment endpoints

| Region | API base URL | |--------|----------------| | EG | https://api.merchant.geidea.net | | KSA / SA | https://api.ksamerchant.geidea.net | | AE / UAE | https://api.geidea.ae |

See Geidea Checkout v2 docs for HPP script URLs and payment flow.