@zaki-g/chargily

A NestJS module for integrating Chargily Pay™ V2 payment gateway into your application.

Installation

npm install @zaki-g/chargily
# or
pnpm install @zaki-g/chargily
# or
yarn add @zaki-g/chargily

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { ChargiliModule } from '@zaki-g/chargily';

@Module({
  imports: [
    ChargiliModule.register({
      api_key: 'your_api_key_here',
      mode: 'test', // or 'live'
    }),
  ],
})
export class AppModule {}

2. Async Configuration (Recommended)

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { ChargiliModule } from '@zaki-g/chargily';

@Module({
  imports: [
    ConfigModule.forRoot(),
    ChargiliModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        api_key: configService.get<string>('CHARGILY_API_KEY'),
        mode: configService.get<'test' | 'live'>('CHARGILY_MODE'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

3. Use the Service

import { Injectable } from '@nestjs/common';
import { ChargiliService } from '@zaki-g/chargily';

@Injectable()
export class PaymentService {
  constructor(private readonly chargilyService: ChargiliService) {}

  async createPayment() {
    const checkout = await this.chargilyService.createCheckout({
      amount: 5000, // Amount in cents (50.00 DZD)
      currency: 'dzd',
      success_url: 'https://your-site.com/success',
      failure_url: 'https://your-site.com/failure',
    });

    return checkout.checkout_url; // Redirect user to this URL
  }
}

Environment Variables

Create a .env file:

CHARGILY_API_KEY=test_pk_your_key_here
CHARGILY_MODE=test

API Reference

Balance

Get your account balance information.

const balance = await chargilyService.getBalance();

→ Chargily Docs: Balance

Customers

Create Customer

const customer = await chargilyService.createCustomer({
  name: 'Ahmed Benali',
  email: '[email protected]',
  phone: '+213555123456',
  address: {
    country: 'DZ',
    state: 'Algiers',
    address: '123 Rue Didouche Mourad',
  },
});

Get Customer

const customer = await chargilyService.getCustomer('customer_id');

Update Customer

const customer = await chargilyService.updateCustomer('customer_id', {
  email: '[email protected]',
});

Delete Customer

await chargilyService.deleteCustomer('customer_id');

List Customers

const customers = await chargilyService.listCustomers(10, 1); // per_page, page

→ Chargily Docs: Customers

Products

Create Product

const product = await chargilyService.createProduct({
  name: 'Premium Subscription',
  description: 'Monthly premium access',
  images: ['https://example.com/image.jpg'],
});

Get Product

const product = await chargilyService.getProduct('product_id');

Update Product

const product = await chargilyService.updateProduct('product_id', {
  name: 'Updated Name',
});

Delete Product

await chargilyService.deleteProduct('product_id');

List Products

const products = await chargilyService.listProducts(10, 1);

Get Product Prices

const prices = await chargilyService.getProductPrices('product_id', 10, 1);

→ Chargily Docs: Products

Prices

Create Price

const price = await chargilyService.createPrice({
  amount: 5000, // 50.00 DZD
  currency: 'dzd',
  product_id: 'product_id',
});

Get Price

const price = await chargilyService.getPrice('price_id');

Update Price

const price = await chargilyService.updatePrice('price_id', {
  metadata: { featured: true },
});

List Prices

const prices = await chargilyService.listPrices(10, 1);

→ Chargily Docs: Prices

Checkouts

Create Checkout

const checkout = await chargilyService.createCheckout({
  items: [
    { price: 'price_id', quantity: 1 }
  ],
  success_url: 'https://your-site.com/success',
  failure_url: 'https://your-site.com/failure',
  customer_id: 'customer_id', // Optional
  locale: 'ar', // 'ar', 'en', or 'fr'
});

// Redirect user to: checkout.checkout_url

Get Checkout

const checkout = await chargilyService.getCheckout('checkout_id');

List Checkouts

const checkouts = await chargilyService.listCheckouts(10, 1);

Get Checkout Items

const items = await chargilyService.getCheckoutItems('checkout_id', 10, 1);

Expire Checkout

await chargilyService.expireCheckout('checkout_id');

→ Chargily Docs: Checkouts

Payment Links

Create Payment Link

const paymentLink = await chargilyService.createPaymentLink({
  name: 'Product Payment',
  items: [
    { 
      price: 'price_id', 
      quantity: 1,
      adjustable_quantity: false 
    }
  ],
  after_completion_message: 'Thank you!',
});

// Share: paymentLink.url

Get Payment Link

const link = await chargilyService.getPaymentLink('payment_link_id');

Update Payment Link

const link = await chargilyService.updatePaymentLink('payment_link_id', {
  name: 'Updated Name',
});

List Payment Links

const links = await chargilyService.listPaymentLinks(10, 1);

Get Payment Link Items

const items = await chargilyService.getPaymentLinkItems('payment_link_id', 10, 1);

→ Chargily Docs: Payment Links

Complete Example

import { Injectable } from '@nestjs/common';
import { ChargiliService } from '@zaki-g/chargily';

@Injectable()
export class OrderService {
  constructor(private readonly chargilyService: ChargiliService) {}

  async processOrder(userId: string, items: any[]) {
    // 1. Create or get customer
    const customer = await this.chargilyService.createCustomer({
      name: 'Customer Name',
      email: '[email protected]',
    });

    // 2. Create checkout
    const checkout = await this.chargilyService.createCheckout({
      items: items.map(item => ({
        price: item.priceId,
        quantity: item.quantity,
      })),
      customer_id: customer.id,
      success_url: `https://your-site.com/orders/${orderId}/success`,
      failure_url: `https://your-site.com/orders/${orderId}/failure`,
      locale: 'ar',
      metadata: {
        order_id: orderId,
        user_id: userId,
      },
    });

    return {
      checkoutId: checkout.id,
      checkoutUrl: checkout.checkout_url,
    };
  }

  async verifyPayment(checkoutId: string) {
    const checkout = await this.chargilyService.getCheckout(checkoutId);
    return checkout.status === 'paid';
  }
}

Payment Flow

1. Create Product & Price → One-time setup
2. Create Customer → Optional, for tracking
3. Create Checkout → Generate payment URL
4. Redirect User → To checkout_url
5. Verify Payment → Check checkout status or use webhooks

→ Full Integration Guide

Webhooks

For webhook handling, refer to Chargily's webhook documentation:

→ Chargily Docs: Webhooks

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import { 
  ChargiliService, 
  Customer, 
  Checkout, 
  Product,
  CreateCheckoutParams 
} from '@zaki-g/chargily';

Error Handling

try {
  const checkout = await chargilyService.createCheckout(data);
} catch (error) {
  console.error('Chargily Error:', error.message);
  // Handle error appropriately
}

Testing

Use test mode for development:

ChargiliModule.register({
  api_key: 'test_pk_...',
  mode: 'test',
})

Get test API keys from Chargily Dashboard.

Resources

• Chargily Pay Documentation
• API Reference
• Chargily Dashboard
• Support

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT © Zaki

Support

• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Chargily Community

Made with ❤️ for the Algerian developer community