I'll help you create a comprehensive README.md file for the HyperPay payment integration:

# HyperPay Payment Integration

This module provides integration with HyperPay payment gateway for handling online payments in your NestJS application.

## Installation

```bash
npm install nestjs-hyperpay-integration

Environment Variables

Create a .env file in your project root and add the following variables:

HYPERPAY_ACCESS_TOKEN=your_access_token
HYPERPAY_ENTITY_ID=your_entity_id
HYPERPAY_MODE=TEST  # or LIVE for production
HYPERPAY_CURRENCY=SAR  # default currency
HYPERPAY_MADA_ENTITY_ID=your_mada_entity_id  # optional
HYPERPAY_APPLE_ENTITY_ID=your_apple_entity_id  # optional

Module Setup

Import and configure the HyperPayModule in your payment module:

@Module({
  imports: [
    HyperPayModule.register({
      accessToken: process.env.HYPERPAY_ACCESS_TOKEN,
      entityId: process.env.HYPERPAY_ENTITY_ID,
      mode: process.env.HYPERPAY_MODE as 'TEST' | 'LIVE',
      currency: process.env.HYPERPAY_CURRENCY,
      mada: {
        entityId: process.env.HYPERPAY_MADA_ENTITY_ID,
      },
      apple: {
        entityId: process.env.HYPERPAY_APPLE_ENTITY_ID,
      },
    }),
  ],
  // ... other module configuration
})

Usage

1. Direct Card Payment

@Injectable()
export class PaymentService {
  constructor(private hyperPayService: HyperPayService) {}

  async processPayment(paymentData: any) {
    const paymentRequest = {
      amount: 100.00,
      currency: 'SAR',
      paymentType: 'DB',
      customer: {
        email: '[email protected]',
        givenName: 'John Doe',
      },
      billing: {
        street1: 'Sample Street',
        city: 'Sample City',
        country: 'SA',
      },
    };

    const cardData = {
      number: '4200000000000000',  // Test card number
      holder: 'John Doe',
      expiryMonth: '05',
      expiryYear: '2034',
      cvv: '123',
    };

    try {
      const result = await this.hyperPayService.prepareCheckout(
        paymentRequest,
        cardData,
        'VISA'  // or 'MASTER', 'MADA', etc.
      );

      // Check payment status
      const status = await this.hyperPayService.getPaymentStatus(result.id);
      return status;
    } catch (error) {
      throw new BadRequestException('Payment failed');
    }
  }
}

2. Supported Card Types

• VISA
• MASTER
• MADA
• APPLEPAY

3. Error Handling

The service throws exceptions for various error cases:

try {
  const result = await this.hyperPayService.prepareCheckout(/* ... */);
} catch (error) {
  if (error.response?.data) {
    // Handle HyperPay API error
    console.error('Payment error:', error.response.data);
  } else {
    // Handle connection/other errors
    console.error('Connection error:', error.message);
  }
}

4. Payment Status Codes

Common status codes returned by HyperPay:

• 000.100.110: Request successfully processed
• 000.200.000: Transaction successful
• 800.400.500: Invalid card data
• 800.400.501: Invalid card number
• 800.400.502: Invalid CVV
• 800.400.503: Invalid expiry date

Security Considerations

1. Never log full card details
2. Always use HTTPS
3. Implement rate limiting
4. Validate all input data
5. Store card data securely (encrypted)

Support

For HyperPay API documentation and support:

• HyperPay Documentation
• Test Environment
• Production Environment

This README provides a comprehensive guide for developers to integrate and use HyperPay in their NestJS applications. Let me know if you need any clarification or additional sections!