airwallex-payment-elements
Version:
> **IMPORTANT NOTICE**: This package is being superseded by [Airwallex.js](https://www.airwallex.com/docs/developer-tools__sdks__airwallex.js__upgrade-to-airwallex.js__upgrade-from-payment-elements-sdk). We strongly recommend upgrading to Airwallex.js for
174 lines (132 loc) • 7.77 kB
Markdown
# airwallex-payment-elements
> **IMPORTANT NOTICE**: This package is being superseded by [Airwallex.js](https://www.airwallex.com/docs/developer-tools__sdks__airwallex.js__upgrade-to-airwallex.js__upgrade-from-payment-elements-sdk). We strongly recommend upgrading to Airwallex.js for the latest features and improvements.
Comprehensive documentation for Airwallex Payment Elements is now available via Airwallex.js. Airwallex.js consolidates all Airwallex Elements into a single, unified SDK for greater efficiency and ease of integration. The SDK includes:
- Payment Elements (Drop-In, HPP, Card, Apple Pay, Google Pay, etc.)
- Payout Elements (Beneficiary, Transfer, Tax Form)
- Onboarding Elements (KYC, KYB)
- Risk Elements (RFI)
- Compliance Support Elements (SCA)
We recommend [upgrading to the new Airwallex.js SDK](https://www.airwallex.com/docs/developer-tools__sdks__airwallex.js__upgrade-to-airwallex.js__upgrade-from-payment-elements-sdk) to access the latest Payment Elements features and enhancements.
[](https://www.npmjs.org/package/airwallex-payment-elements)
[](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', // '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
```