EasyPay

A TypeScript/JavaScript client to integrate payment services (Chapa, Telebirr, M-Pesa, CBE Birr) easily in web or Node.js applications. Supports inline payments, hosted payments, and automatic payment verification with retries.

Installation

npm install @realkal/easy-pay
# or
yarn add @realkal/easy-pay
pnpm add @realkal/easy-pay

Importing

import { easyPay } from "@realkal/easy-pay";

Client Configuration (easyPay)

| Option | Type | Required | Default | Description | | ---------------- | ---------- | -------- | ----------------------------------------------------------------------- | --------------------------------------------- | | publicKey | string | ✅ | - | Chapa public key | | secretKey | string | ❌ | - | Chapa secret key, required for Chapa payments and transaction verification | | paymentOptions | string[] | ❌ | ["telebirr", "cbebirr", "ebirr", "mpesa", "chapa"] | Allowed payment methods | | callbackUrl | string | ❌ | - | URL to receive server-side callback | | returnUrl | string | ❌ | - | URL to redirect after payment | | generateRefId | () => string | ❌ | Random nanoid(10) | Custom transaction reference generator | | onSuccess | (paymentInfo: any) => void | ❌ | () => {} | Callback after successful payment | | onFailure | (error: string) => void | ❌ | () => {} | Callback after failed payment | | maxRetry | number | ❌ | 3 | Max retries for pending payments | | retryDelay | number | ❌ | 3 | Delay between retries in seconds |

Payment Properties (CreatePaymentProps)

| Property | Type | Required | Description | | --------------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------- | | mobile | string | ✅ | User phone number, validated per payment type | | paymentType | "telebirr" \| "cbebirr" \| "ebirr" \| "mpesa" \| "chapa" | ✅ | Payment method | | amount | number | ✅ | Payment amount (minimum 1) | | txRef | string | ❌ | Optional transaction reference, auto-generated if missing | | email | string | ❌ | Customer email | | first_name | string | ❌ | Customer first name | | last_name | string | ❌ | Customer last name | | customization | object | ❌ | Payment UI customization options | | meta | Record<string, any> | ❌ | Extra metadata attached to the payment |

Customization example:

customization: {
  logo?: string;
  title?: string;
  description?: string;
}

Meta example:

meta: {
  userId: "123",
  campaignId: "456",
  note: "Special instructions"
}

Usage Examples (Updated for EasyPayResponse)

1. Basic Chapa Payment

const easyPayClient = new easyPay({
  publicKey: "CHAPUBK-xxxxxxxx",
  secretKey: "CHASECK-xxxxxxxx",
});

const result = await easyPayClient.createPayment({
  mobile: "0900123456",
  amount: 500,
  paymentType: "chapa",
  first_name: "John",
  last_name: "Doe",
  email: "[email protected]",
});

if (result.success) {
  console.log("Payment initiated successfully:", result.data);
} else {
  console.error("Payment failed:", result.message);
}

2. Payment with Customization

const result = await easyPayClient.createPayment({
  mobile: "0700123456",
  amount: 300,
  paymentType: "mpesa",
  customization: {
    logo: "https://example.com/logo.png",
    title: "Donation",
    description: "Support our cause",
  },
});

if (result.success) {
  console.log("Payment initiated successfully:", result.data);
} else {
  console.error("Payment failed:", result.message);
}

3. Payment with Metadata

const result = await easyPayClient.createPayment({
  mobile: "0900123456",
  amount: 200,
  paymentType: "telebirr",
  meta: {
    campaignId: "CAMPAIGN123",
    userId: "USER456",
    notes: "Priority user",
  },
});

if (result.success) {
  console.log("Payment initiated successfully:", result.data);
} else {
  console.error("Payment failed:", result.message);
}

4. Payment with Custom txRef

const result = await easyPayClient.createPayment({
  mobile: "0900123456",
  amount: 1000,
  paymentType: "chapa",
  txRef: "CUSTOM_REF_123",
  meta: { orderId: "ORDER789" },
});

if (result.success) {
  console.log("Payment initiated successfully:", result.data);
} else {
  console.error("Payment failed:", result.message);
}

5. Full Example (All Options)

const easyPayClient = new easyPay({
  publicKey: "CHAPUBK-xxxxxxxx",
  secretKey: "CHASECK-xxxxxxxx",
  callbackUrl: "https://example.com/callback",
  returnUrl: "https://example.com/return",
  maxRetry: 5,
  retryDelay: 5,
  onSuccess: (paymentInfo) => console.log("Payment succeeded:", paymentInfo),
  onFailure: (error) => console.log("Payment failed:", error),
});

const paymentResult = await easyPayClient.createPayment({
  mobile: "0900123456",
  amount: 750,
  paymentType: "telebirr",
  first_name: "John",
  last_name: "Doe",
  email: "[email protected]",
  customization: {
    logo: "https://example.com/logo.png",
    title: "Charity Donation",
    description: "Support our campaign",
  },
  meta: {
    userId: "USER123",
    campaignId: "CAMPAIGN456",
    note: "VIP user",
  },
});

if (paymentResult.success) {
  console.log("Payment data:", paymentResult.data);
} else {
  console.error("Payment error:", paymentResult.message);
}

6. Verify Transaction Server-Side (New)

You can verify any Chapa transaction server-side using verifyTransaction with the secretKey.

const transactionResult = await easyPayClient.verifyTransaction("TX_REF_123");

if (transactionResult.success) {
  console.log("Transaction verified successfully:", transactionResult.data);
} else {
  console.error("Transaction verification failed:", transactionResult.message);
}

Payment Verification

const verification = await easyPayClient.verifyPayment("TX_REF_123", "chapa");

if (verification.success) {
  console.log("Payment verified successfully:", verification.data);
} else {
  console.error("Payment verification failed:", verification.message);
}

• Automatically retries if the payment is pending.
• Calls onSuccess or onFailure callbacks automatically.
• Retry behavior is configurable via maxRetry and retryDelay.

Return Type (EasyPayResponse)

type EasyPayResponse = {
  success: boolean;
  message: string;
  data?: {
    checkoutUrl?: string; // For Chapa hosted
    txRef?: string;       // For mobile money
    amount?: string;
    status?: string;
    createdAt?: string;
  } | null;
};

• Both createPayment, verifyPayment, and verifyTransaction now always return EasyPayResponse.
• message is always a string.
• data is either a populated object or null.

Notes

• Supports multiple payment methods in the same configuration.
• Chapa payments and transaction verification require secretKey; others do not.
• Inline payments automatically verify transactions.
• Hosted payments return a checkout_url.
• Return types are fully type-safe and consistent.

License

MIT © Endekalu Zemenu