airwallex-payment-elements/README.md

[](https://www.npmjs.org/package/airwallex-payment-elements) [](https://git

# airwallex-payment-elements

[![Version](https://img.shields.io/npm/v/airwallex-payment-elements.svg)](https://www.npmjs.org/package/airwallex-payment-elements)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

This airwallex-payment-elements library is a lightweight javascript SDK that allows merchants to conveniently integrate the Airwallex checkout flow on their website.

Check out our demo [here](https://demo-pacheckoutdemo.airwallex.com/).

# How it works

Merchants can integrate airwallex-payment-elements in the checkout page on their site. For every checkout, merchants should create a [PaymentIntent](https://www.airwallex.com/docs/api#/Payment_Acceptance/Payment_Intents/) entity through the [Airwallex API](https://www.airwallex.com/docs/api) to process payments with Airwallex.

Once the PaymentIntent is successfully created via API integration, the API will return a response with a unique ID and client secret for the intent. Merchants can then use these two keys to enable the payment elements to collect payment attempt details.

# Payment Methods

The package includes different payment processing elements that will allow merchants ot accept payments on their site. We have 6 different checkout elements:

- [**Hosted Payment Page (HPP)**](https://www.airwallex.com/docs/payments__hosted-payment-page-integration): _Merchants can accept payments without the full handling of the payment processing and display of the payment options._
- [**Drop in**](https://www.airwallex.com/docs/payments__drop-in-integration): _Merchants can accept payments without full responsibility of handling their payments but can still control the overall look and feel of their payment page._
- [**Embedded Fields (Elements)**](https://www.airwallex.com/docs/payments__embedded-fields-integration): _A set of prebuilt UI components, like inputs and buttons that Merchants can directly place in their checkout flow (more below)_
  - Full Featured Card
  - Split Card
  - Wechat Element

The primary focus of this library is **_Elements_**, which enables Merchants to collect sensitive information (PCI) using customizable UI elements. This library also provides a single interface for interacting with the Payment Request API, allowing for the tokenization of sensitive information and handling of 3D secure authentication flows.

Elements includes the following features:

1. Automatic formatting of card information in the input field
2. Customize placeholders to fit Merchant UX/UI designs
3. Responsive design
4. Flexible/Customizable styling to match the look and feel of the Merchant's checkout flow

# Installation

Install with Yarn

```
yarn add airwallex-payment-elements
```

Or, with NPM

```
npm install airwallex-payment-elements
```

# Getting Started with the Airwallex Card Element

The Card element is one of Airwallex's most popular payment integration. It is a single line multi-input field containing card number, card expiry, and card cvc.

_Detailed Card integration guide [here](https://github.com/airwallex/airwallex-payment-demo/blob/master/docs/card.md). More extensive documentation details [below](#Documentation)_

### Initialize Airwallex:

```ts
import Airwallex from 'airwallex-payment-elements';

Airwallex.loadAirwallex({
  env: 'demo', // 'staging' | 'demo' | 'prod'
});
```

### Create a container for your payment element in HTML:

```html
<div id="card"></div>
<div id="submit">Submit</div>
```

### Then create and mount your payment element in Javascript:

```ts
const cardElement = Airwallex.createElement('card', {
  intent: {
    // Required, Card uses intent Id and client_secret to prepare checkout
    id: 'replace-with-your-intent-id',
    client_secret: 'replace-with-your-client-secret',
  },
});
cardElement.mount('card'); // Injects iFrame into element container
```

### Add an event handler to the button to trigger payment confirmation

```ts
document.getElementById('submit').addEventListener('click', () => {
  Airwallex.confirmPaymentIntent({
    element: card, // Must link element
    id: 'replace-with-your-intent-id', // Same as intent details from above
    client_secret: 'replace-with-your-client-secret',
  }).then((response) => {
    // Listen to the payment confirmation response
    window.alert(JSON.stringify(response));
  });
});
}
```

### Add `onReady`, `onChange`, `onSuccess`, and `onError` event listeners to handle various events received from the Airwallex Payment server.

```ts
// Replace EVENT_TYPE with 'onReady', 'onChange', 'onSuccess', or 'onError'
window.addEventListener(EVENT_TYPE, (event) => {
  /*
  ... Handle event
    */
  window.alert(event.detail);
});
```

# Integration

Each payment processing method requires different customizations. Check out our examples of web integrations with the [airwallex-payment-demo](https://github.com/airwallex/airwallex-payment-demo) library.

# Sandboxes

You also can play around with different elements in our framework specific sandboxes below. They're all based off the [airwallex-payment-demo](https://github.com/airwallex/airwallex-payment-demo) repository!

- [Static HTML](https://codesandbox.io/s/airwallex-payment-demo-static-html-c2z63)
- [React](https://codesandbox.io/s/airwallex-payment-demo-react-2m63j)
- [React-Typescript](https://codesandbox.io/s/airwallex-payment-demo-react-typescript-buuhk)
- [Vue](https://codesandbox.io/s/airwallex-payment-demo-vue-ffhrw)
- [Angular](https://codesandbox.io/s/airwallex-payment-demo-angular-zgx32)

# Questions, comments, or suggestions?

We want to provide you with a seamless experience integrating with our platform. [Let us know](https://www.airwallex.com/contact-sales) if you run into any problems, or have any comments and suggestions for us. We value your input!

```bash
.
├── dist
│   ├── index.d.ts
│   ├── index.js
│   └── index.js.map
├── docs # GATSBY DOC PROJECT
│   ├── gatsby-config.js
│   ├── package.json
│   ├── plugins
│   ├── public
│   ├── scripts
│   ├── source
│   │   ├── basic-usage # MANUAL MAINTAINED BY DEVELOPERS
│   │   ├── index.mdx # TECHNICAL OVERVIEW
│   │   └── sdk-reference # GENERATED BY TYPEDOC
│   ├── src
│   ├── tsconfig.json
│   └── yarn.lock
├── src
│   ├── __snapshots__
│   ├── index.test.ts
│   └── index.ts
├── types
│   ├── airwallex.d.ts
│   ├── element.d.ts
├── package.json
├── tsconfig.json
├── .gitlab-ci.yml # ADD DOC PROJECT BUILD AND DEPLOYMENT STAGE
├── typedocconfig.js # TYPEDOC CONFIG
└── yarn.lock
```