blink-pay Library

blink-pay is an Angular library that integrates Adyen's payment services to handle credit card (CC) and ACH payments, supporting both simultaneous and independent usage of these payment methods. It provides reusable payment components with customizable configurations and a focus on ease of integration.

Table of Contents

• Installation
• Usage
  • Basic Usage
  • Configuration Options
• Available Components
  • BlinkPayComponent
• Events
• Services
• Error Handling
• Testing
• Publishing to GitHub Packages
• Contributing

Installation

To install the library from your GitHub Packages registry:

1. Configure NPM to use GitHub as the registry by creating a .npmrc file in the root of your project:

   @your-github-username:registry=https://npm.pkg.github.com

   Ensure you are logged into GitHub Packages:

Usage

Basic Usage

1. Import the BlinkPayModule in your Angular module:

import { BlinkPayModule } from '@your-github-username/blink-pay';

@NgModule({
  declarations: [...],
  imports: [
    BlinkPayModule.forRoot({
      clientKey: 'your-client-key',
      locale: 'en-US',
      environment: 'test',
      paymentMethods: {}
    }),
    ...
  ]
})
export class AppModule {}

2. Use the component in your template:

<blink-pay 
  [generalConfig]="generalConfig" 
  [uiConfig]="uiConfig" 
  [styles]="styles"
  (sendSubmitEvent)="onSubmit($event)"
></blink-pay>

Configuration Options

• General Configuration (TGeneralConfiguration):
  • clientKey (string): The Adyen client key.
  • locale (string): The locale (e.g., en-US).
  • environment (string): Adyen environment (test or live).
  • paymentMethods (object): Available payment methods fetched from the Adyen API.
• UI Configuration (TUIConfiguration):
  • hasHolderName (boolean): Whether the card holder’s name is required.
  • positionHolderNameOnTop (boolean): Whether the holder name field is at the top of the form.
  • holderNameRequired (boolean): Whether the holder name is mandatory.
  • billingAddressRequired (boolean): Whether billing address is required.
• Styles Configuration (TStylesConfig):
  • Customize the styles of the payment component using CSS.
  • Styling format can be referenced here: https://docs.adyen.com/payment-methods/cards/custom-card-integration/#styling

Available Components

BlinkPayComponent

A reusable Angular component that integrates with Adyen’s Card and ACH payment methods.

Input Properties:

• generalConfig: General settings such as clientKey, environment, and locale.

• uiConfig: Configuration options for customizing the appearance and behavior of the payment form.

• styles: Optional styles for the payment form.

  Output Events:

• sendSubmitEvent: Emits when the form is submitted.

• sendErrorOccuredEvent: Emits when an error occurs during payment processing.

• sendFormValueChangedEvent: Emits when form values change and validation states update.

Available Components

The BlinkPayComponent emits various events to inform the parent component of form state changes, errors, and submissions:

1. sendSubmitEvent: Emitted when the payment form is successfully submitted.
2. sendErrorOccuredEvent: Emitted when an error occurs during the payment process.
3. sendFormValueChangedEvent: Emitted when the form values change.
4. sendBinLookupEvent: Emitted during BIN (Bank Identification Number) lookup.

Services

• CardService: Handles card-related logic and validation.

Error Handling

The library provides a comprehensive error handling system through the ErrorHandler class. It categorizes errors into:

• Network errors
• Cancellations
• Implementation errors
• Generic errors

To handle errors emitted by the component:

<blink-pay (sendErrorOccuredEvent)="onError($event)"></blink-pay>

Testing

The module is set up with Jasmine & Karma for unit testing. Run tests using:

ng test blink-pay

Ensure you have code coverage enabled for testing critical paths like payment submissions and error handling.

Publishing to GitHub Packages

To publish the blink-pay module to GitHub Packages, follow these steps:

1. Ensure you’re logged into NPM:

npm login --registry=https://npm.pkg.github.com

2. Run the publish script:

npm run publish:blink-pay

The package will be built and pushed to your GitHub Packages registry.

Usefull links

1. https://github.com/adyen-examples
2. https://docs.adyen.com/api-explorer/Checkout/71/post/sessions
3. https://github.com/Adyen/adyen-web?tab=readme-ov-file#readme
4. https://docs.adyen.com/payment-methods/cards/web-component/#create-a-token