💳 Fawry Checkout Link

A simple and secure TypeScript/JavaScript package for generating FawryPay payment checkout links.

✨ Features

• ✅ Production & Staging Support - Seamlessly switch between environments
• ✅ Type Safety - Built with TypeScript for better developer experience
• ✅ Input Validation - Comprehensive validation before API requests
• ✅ Multiple Items Support - Add multiple items in a single checkout
• ✅ Multilingual Support - English and Arabic language support
• ✅ Secure Signatures - SHA-256 based secure signature generation

📦 Installation

npm install fawry-checkout-link

🚀 Quick Start

import { checkoutLink, CheckoutLinkProps } from "fawry-checkout-link";

const paymentData: CheckoutLinkProps = {
  mode: "production", // or 'staging'
  merchantCode: "YOUR_MERCHANT_CODE",
  secureKey: "YOUR_SECURE_KEY",
  customerProfileId: "CUSTOMER_123",
  returnUrl: "https://yoursite.com/payment-complete",
  items: [
    {
      itemId: "item-001",
      description: "Premium Subscription",
      price: 99.99,
      quantity: 1,
    },
  ],
};

try {
  const paymentUrl: string = await checkoutLink(paymentData);
  console.log("Payment URL:", paymentUrl);
  // Redirect user to the payment page
} catch (error) {
  console.error("Payment failed:", error);
}

📖 API Reference

checkoutLink(paymentData)

Generates a FawryPay checkout link.

Type Signature:

function checkoutLink(paymentData: CheckoutLinkProps): Promise<string>

Parameters:

• paymentData (CheckoutLinkProps) - Payment configuration object

Returns:

• Promise<string> - The payment checkout URL

⚙️ Configuration Options

CheckoutLinkProps

interface CheckoutLinkProps {
  mode: "staging" | "production";
  merchantCode: string;
  secureKey: string;
  customerProfileId: string;
  returnUrl: string;
  items: ChargeItem[];
  customerName?: string;
  customerEmail?: string;
  customerMobile?: string;
  language?: "en-gb" | "ar-eg";
  paymentExpiry?: number;
  authCaptureModePayment?: boolean;
}

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | mode | "staging" \| "production" | ✅ Yes | - | API environment to use | | merchantCode | string | ✅ Yes | - | Your Fawry merchant code | | secureKey | string | ✅ Yes | - | Your Fawry secure key | | customerProfileId | string | ✅ Yes | - | Unique customer identifier | | returnUrl | string | ✅ Yes | - | URL to redirect after payment | | items | ChargeItem[] | ✅ Yes | - | Array of items to charge | | customerName | string | ❌ Optional | - | Customer's full name | | customerEmail | string | ❌ Optional | - | Customer's email address | | customerMobile | string | ❌ Optional | - | Customer's mobile number | | language | "en-gb" \| "ar-eg" | ❌ Optional | "en-gb" | Payment page language | | paymentExpiry | number | ❌ Optional | 1631138400000 | Payment expiry timestamp | | authCaptureModePayment | boolean | ❌ Optional | false | Auth capture mode |

ChargeItem

interface ChargeItem {
  itemId: string;
  description?: string;
  price: number;
  quantity: number;
  imageUrl?: string;
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | itemId | string | ✅ Yes | Unique item identifier | | price | number | ✅ Yes | Item price | | quantity | number | ✅ Yes | Item quantity | | description | string | ❌ Optional | Item description | | imageUrl | string | ❌ Optional | Item image URL |

💡 Examples

Basic Example

import { checkoutLink, CheckoutLinkProps } from "fawry-checkout-link";

const paymentData: CheckoutLinkProps = {
  mode: "staging",
  merchantCode: "your-merchant-code",
  secureKey: "your-secure-key",
  customerProfileId: "CUSTOMER_123",
  returnUrl: "https://yourapp.com/success",
  items: [
    {
      itemId: "product-1",
      price: 50.00,
      quantity: 1,
    },
  ],
};

const url: string = await checkoutLink(paymentData);

Advanced Example with Multiple Items

import { checkoutLink, CheckoutLinkProps, ChargeItem } from "fawry-checkout-link";

const items: ChargeItem[] = [
  {
    itemId: "prod-123",
    description: "Premium Plan - Monthly",
    price: 299.99,
    quantity: 1,
    imageUrl: "https://example.com/premium.jpg",
  },
  {
    itemId: "prod-456",
    description: "Add-on Feature",
    price: 49.99,
    quantity: 2,
    imageUrl: "https://example.com/addon.jpg",
  },
];

const paymentData: CheckoutLinkProps = {
  mode: "production",
  merchantCode: "your-merchant-code",
  secureKey: "your-secure-key",
  customerProfileId: "user_789",
  customerName: "Ahmed Mohamed",
  customerEmail: "[email protected]",
  customerMobile: "010++++++++",
  returnUrl: "https://yourapp.com/return",
  items: items,
  language: "ar-eg", // default "en-gb"
  paymentExpiry: Date.now() + 24 * 60 * 60 * 1000, // 24 hours from now 
};

try {
  const url: string = await checkoutLink(paymentData);
  window.location.href = url; // Redirect in browser
} catch (error) {
  console.error("Payment error:", error);
}

❌ Error Handling

The package returns helpful error messages when validation fails. Always wrap your calls in try-catch blocks:

try {
  const url: string = await checkoutLink(paymentData);
  // Handle success
} catch (error: unknown) {
  if (typeof error === "string") {
    // Validation error
    console.error("Validation error:", error);
  } else if (error instanceof Error) {
    // API error
    console.error("API error:", error.message);
  } else {
    // Unknown error
    console.error("Unknown error:", error);
  }
}

Common Validation Errors

• "Mode Environment is required (production / staging)" - Missing or invalid mode
• "Merchant code and secure key are required" - Missing credentials
• "Valid customerProfileId is required" - Missing customer ID
• "At least one item is required" - No items in cart
• "'itemId' in item X is required" - Missing item ID
• "'price' in item X is required" - Missing item price
• "'quantity' in item X is required" - Missing item quantity
• "Return URL is required" - Missing return URL

🔒 Security

This package implements several security features:

• ✅ SHA-256 Signatures - All requests are signed using SHA-256 hashing
• ✅ Input Validation - All inputs are validated before processing
• ✅ Safe Error Messages - Errors don't expose sensitive information
• ✅ Secure API Communication - Uses HTTPS for all API calls

Best Practices

1. Never expose your secure key - Keep it in environment variables
2. Use HTTPS - Always use HTTPS in production
3. Validate on server - Always validate payment data on your server

// ❌ BAD: Don't hardcode credentials
const secureKey: string = "your-secure-key";

// ✅ GOOD: Use environment variables
const secureKey: string = process.env.FAWRY_SECURE_KEY!;

📚 Reference

• FawryPay Developer Documentation: https://developer.fawrystaging.com/docs/express-checkout/fawrypay-hosted-checkout
• Production API: https://atfawry.com/fawrypay-api/api/payments/init
• Staging API: https://atfawry.fawrystaging.com/fawrypay-api/api/payments/init

👨‍💻 Author

Mohamed Elsebaey

• GitHub: @mohamed-elsebaey
• Website: elsebaey.vercel.app

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.