Moolre Payments

Moolre is a payment technology company providing seamless payment solutions across Ghana and Nigeria. This guide covers how to integrate Moolre payments using Voltax.

Prerequisites

Before you begin, you’ll need:

• A Moolre merchant account (sign up at moolre.com)
• Your Moolre API credentials:
  • Public API Key
  • Moolre Username
  • Moolre Wallet Account Number

Caution

Never expose your credentials in client-side code. Always keep them secure on your server.

Configuration

Initialize a Moolre provider with your credentials:

import Voltax from "@noelzappy/voltax";

const moolre = Voltax("moolre", {
  apiUser: process.env.MOOLRE_USERNAME!,
  apiPublicKey: process.env.MOOLRE_PUBLIC_API_KEY!,
  accountNumber: process.env.MOOLRE_WALLET_ACCOUNT_NUMBER!,
});

Initiate a Payment

Required Fields

Moolre has specific requirements that differ from other providers: - reference is required - callbackUrl is required - redirectUrl is required

Basic Payment

import { Currency } from "@noelzappy/voltax";

const payment = await moolre.initiatePayment({
  amount: 5000, // 5,000 GHS
  email: "customer@example.com",
  currency: Currency.GHS,
  reference: `txn-${Date.now()}`,
  callbackUrl: "https://yoursite.com/webhook/callback",
  redirectUrl: "https://yoursite.com/payment/redirect",
});

// Redirect customer to complete payment
console.log(payment.authorizationUrl);
// "https://checkout.moolre.com/xxxxxxxxxx"

With Metadata

Attach Metadata. Moolre will automatically return this to you during their callback/webhook call to you.

import { Currency } from "@noelzappy/voltax";

const payment = await moolre.initiatePayment({
  amount: 5000, // 5,000 GHS
  email: "customer@example.com",
  currency: Currency.GHS,
  reference: `txn-${Date.now()}`,
  callbackUrl: "https://yoursite.com/webhook/callback",
  redirectUrl: "https://yoursite.com/payment/redirect",
  metadata: {
    customer_id: "12345",
    order_id: "67890",
  },
});

// Redirect customer to complete payment
console.log(payment.authorizationUrl);
// "https://checkout.moolre.com/xxxxxxxxxx"

Reusable Authorization URL

Generate a reusable authorization URL that can be used to initiate payments without requiring user input.

import { Currency } from "@noelzappy/voltax";

const payment = await moolre.initiatePayment({
  amount: 5000, // 5,000 GHS
  email: "customer@example.com",
  currency: Currency.GHS,
  reference: `txn-${Date.now()}`,
  callbackUrl: "https://yoursite.com/webhook/callback",
  redirectUrl: "https://yoursite.com/payment/redirect",
  linkReusable: true, // This controls whether the authorization URL can be reused for multiple payments. By default, it is set to false.
  metadata: {
    customer_id: "12345",
    order_id: "67890",
  },
});

// Redirect customer to complete payment
console.log(payment.authorizationUrl);
// "https://checkout.moolre.com/xxxxxxxxxx"

With All Options

const payment = await moolre.initiatePayment({
  amount: 250,
  email: "customer@example.com",
  currency: Currency.GHS,
  reference: `order-${Date.now()}`,
  description: "Order #12345 - Premium Package",
  callbackUrl: "https://yoursite.com/webhooks/moolre",
  redirectUrl: "https://yoursite.com/payment/redirect",
  linkReusable: true,
  accountNumberOverride: "1234567890",
  metadata: {
    customer_id: "12345",
    order_id: "67890",
  },
});

Moolre-Specific Options

All Moolre-specific options are top-level fields in the payment DTO:

interface MoolrePaymentDTO {
  // Base required fields
  amount: number;
  email: string;
  currency: Currency;
  reference: string; // Required for Moolre
  callbackUrl: string; // Required for Moolre

  // Moolre-specific required
  redirectUrl: string; // Where to redirect after successful payment

  // Optional fields
  linkReusable?: boolean; // Whether the authorization URL can be reused
  accountNumberOverride?: string; // Override the account/wallet number
  description?: string;
  metadata?: Record<string, any>;
}

Understanding the URLs

URL	Purpose
callbackUrl	Server-to-server webhook URL for payment notifications
redirectUrl	Where to redirect the customer after successful payment

Callback vs Redirect URL

• callbackUrl: Your backend endpoint that receives payment status updates (webhook) - redirectUrl: The page your customer sees after payment completion

Verify a Transaction

After the customer completes payment, verify the transaction:

import { PaymentStatus } from "@noelzappy/voltax";

const result = await moolre.verifyTransaction("123456");

console.log(result);
// {
//   status: 'SUCCESS',
//   reference: 'moolre-123456',
//   externalReference: 'txn_xxxxxxxxxx',
//   raw: { ... }
// }

if (result.status === PaymentStatus.SUCCESS) {
  // Access detailed transaction data
  console.log(result.reference);
}

Status Mapping

Voltax maps Moolre statuses to standardized values:

Moolre Status	Voltax Status
1	SUCCESS
0	PENDING
2	FAILED
Other	PENDING

Get Payment Status

For a quick status check:

const status = await moolre.getPaymentStatus("mool-123456");

if (status === PaymentStatus.SUCCESS) {
  console.log("Payment successful!");
}