NGX-Hyperpay

An Angular library for easy integration of the HyperPay payment gateway. This library provides a component that wraps the HyperPay COPYandPAY integration, making it simple to add a payment form to your Angular application.

Installation

Install the package from npm:

npm install ngx-hyperpay

Backend Integration Required

Security Note: Do NOT perform sensitive operations (like generating checkout IDs or querying payment status with authorization tokens) on the client-side.

1. Generate Checkout ID: Call your backend API to Request a checkoutId from HyperPay using your secret entityId and authorization token.
2. Pass to Component: Pass the received checkoutId to the ngx-hyperpay component.
3. Handle Callback: When the payment is complete, HyperPay redirects to your shopperResultUrl. The component will emit the resourcePath (or id).
4. Verify Payment: Send this resourcePath to your backend. Your backend should then query HyperPay's status API using this path to confirm the payment validity and status.

Usage

1. Import the NgxHyperpayComponent in your component or module:

import { NgxHyperpayComponent } from 'ngx-hyperpay';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [NgxHyperpayComponent],
  template: `
    <ngx-hyperpay
      [checkoutId]="checkoutId"
      [brands]="'VISA MASTER MADA'"
      [mode]="'test'"
      [shopperResultUrl]="'https://your-domain.com/callback'" 
      [redirectUrl]="'https://your-domain.com/home'"
      (onSuccess)="onPaymentSuccess($event)"
      (onFailure)="onPaymentFailure($event)"
      (onCancel)="onPaymentCancel($event)"
      (onError)="onPaymentError($event)"
    ></ngx-hyperpay>
  `
})
export class MyComponent {
  checkoutId = 'YOUR_CHECKOUT_ID'; // Obtain this from your server

  onPaymentSuccess(data: any) {
    console.log('Payment successful:', data);
  }

  onPaymentFailure(data: any) {
    console.log('Payment failed:', data);
  }

  onPaymentCancel(data: any) {
    console.log('Payment cancelled:', data);
  }

  onPaymentError(error: any) {
    console.error('An error occurred:', error);
  }
}

API

Inputs

| Input | Type | Default | Description | | --------------- | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | | checkoutId | string | Required | The checkout ID obtained from your server-side integration with HyperPay. | | brands | string | 'VISA MASTER MADA' | A space-separated list of payment brands to display (e.g., 'VISA MASTER AMEX'). | | mode | 'test' | 'live' | 'test' | The mode for the HyperPay script. Use 'test' for development and 'live' for production. | | style | 'card' | 'plain' | 'card' | The visual style of the payment form. | | locale | 'en' | 'ar' | 'en' | The language of the payment widget. | | shopperResultUrl| string | '' | The custom callback URL to redirect to after payment. Overrides redirectUrl and default behavior. | | redirectUrl | string | '' | The URL to redirect to after the payment. Defaults to the current URL. |

Outputs

| Output | EventEmitter<any> | Description | | ----------- | ---------------------- | ------------------------------------------------------ | | onReady | void | Emitted when the HyperPay widget is ready. | | onSuccess | any | Emitted when the payment is successful. | | onFailure | any | Emitted when the payment fails. | | onCancel | any | Emitted when the user cancels the payment. | | onError | any | Emitted when an error occurs (e.g., script fails to load). | | getResourcePath| string | Emitted when resourcePath query parameter is found (decoded). | | getRawResourcePath| string | Emitted when resourcePath query parameter is found (raw encoded). | | getId | string | Emitted when id query parameter is found (decoded). | | getRawId | string | Emitted when id query parameter is found (raw encoded). |

Development

This library was generated with Angular CLI.

Build

Run ng build ngx-hyperpay to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build ngx-hyperpay, go to the dist folder cd dist/ngx-hyperpay and run npm publish.

Repository

The source code is available on GitLab.