Payment Elements SDK

• Configuration
• Create payment card
• Capture payment
• Pay now
• Void payment
• Types
• Error handling

Getting started

1npm install @eonx/payment-elements
2yarn add @eonx/payment-elements

Configuration

1import { configurePaymentElements } from '@eonx/payment-elements';
2
3configurePaymentElements({
4  /**
5   * Set it as true if you are working in a test environment
6   **/
7  test: true,
8  /**
9   * Change input behavior to floating label
10   **/
11  inputFloatLabel: true,
12  /**
13   * If true the expiry date will be in MM/YYYY, else MM/YY
14   **/
15  expiryFullYear: true,
16  themes: {
17    /**
18     * Global settings for all themes
19     */
20    base: {
21      fonts: [
22        {
23          css: 'https://fonts.googleapis.com/css2?family=Lato:wght@400;700&family=Roboto&display=swap',
24        },
25      ],
26      styles: {
27        fontFamily: 'Lato',
28        fontSizeBase: '12px',
29        fontSizeSmall: '15px',
30        colorPrimary: '#6366f1',
31        colorBorder: '#e0e0e0',
32        colorDanger: '#e53935',
33        colorSuccess: '#22c55e',
34        colorText: '#37474f',
35        colorPlaceholder: '#78909c',
36        colorDivider: '#e5e7eb',
37        colorInputLabel: '#455a64',
38        colorInputBackground: '#fff',
39        colorTextLight: 'gray',
40        borderRadius: '6px',
41        spacing: '10px',
42        spacingLabel: '2px',
43        inputHeight: '44px',
44        buttonHeight: '46px',
45      },
46    },
47    /**
48     * Global settings will be inherited and overrode here
49     */
50    custom: {
51      fonts: [
52        {
53          family: 'Poppins',
54          weight: '400',
55          display: 'swap',
56          src: `url(${window.location.origin}/fonts/poppins-regular.woff2)`,
57        },
58      ],
59      styles: {
60        fontFamily: 'Poppins',
61        fontSizeBase: '16px',
62      },
63    },
64  },
65});

You may update the configuration at the runtime.

1configurePaymentElements({
2  theme: 'dark',
3});

Create payment card

1import {
2  createPaymentCard,
3  ApiError,
4  FrameError,
5  CreateCardError,
6  PaymentCardTokenizeResult,
7} from '@eonx/payment-elements';
8
9const element = createPaymentCard({
10  /**
11   * Predefined values: 'light' or 'dark'.
12   * You can pass custom theme created by `createTheme` method.
13   */
14  theme: 'light',
15  /**
16   * API key with access to the payment API.
17   */
18  apiKey: '-api-key-',
19  /**
20   * HTML container where the payment element will be mounted.
21   */
22  container: 'container-id',
23  /**
24   * Initial value for the cardholder field
25   */
26  cardholder: 'Joe Black',
27  onSuccess(response: PaymentCardTokenizeResult) {
28    // Callback when credit card created
29  },
30  onError(error: Error<CreateCardError | FrameError | ApiError>) {
31    // Callback when any errors occurring with element
32  },
33  onProcess() {
34    // Callback when form submitting.
35  },
36  onChange(event: {
37    data: CardDetails;
38    isValid: boolean;
39    isReadyToSubmit: boolean;
40  }) {
41    // Form values changed
42  },
43  onMounted() {
44    // The form is ready to display
45  },
46});
47
48/**
49 * Element will be automatically disposed when container will be removed from DOM.
50 * Use dispose method if you need to cancel element manually.
51 */
52element.dispose();
53
54/**
55 * Send submit event to form
56 */
57element.submit();
58
59/**
60 * Pre-fill form. Partial values is allowed.
61 */
62element.prefill({
63  cardholder: 'Test User',
64  number: '5123450000000008',
65  cvc: '100',
66  expiryMonth: 1,
67  expiryYear: 2039,
68});
69
70element.prefill({
71  cardholder: 'Test User',
72});
73
74/**
75 * Submit on the form will not be triggered
76 */
77element.disableSubmit();
78
79/**
80 * Cancel form disabling by previous method.
81 */
82element.enableSubmit();
83
84/**
85 * Change theme after the element has been created.
86 */
87element.changeTheme('dark');

Types

1interface CardDetails {
2  cardholder: string;
3  number: string;
4  cvc: string;
5  expiryMonth: number;
6  expiryYear: number;
7}

Result

1interface PaymentCardTokenizeResult {
2  cardholder: string;
3  createdAt: string;
4  currency: {
5    id: string;
6    name: string;
7    createdAt: string;
8    updatedAt: string;
9  };
10  customer: {
11    createdAt: string;
12    fullName: string;
13    id: string;
14    updatedAt: string;
15  };
16  description: string;
17  expiryMonth: number;
18  expiryYear: number;
19  hash: string;
20  id: string;
21  pan: string;
22  paymentMethodType: PaymentMethodType;
23  provider: {
24    name: string;
25    id: string;
26    createdAt: string;
27    updatedAt: string;
28  };
29  reference: string;
30  status: 'inactive' | 'active';
31  updatedAt: string;
32  verified: boolean;
33}

Error Codes

Code	Description
10	API key required
11	Payment API URL not found
12	Unhandled API error
20	HTML container required
21	Failed to render payment UI
22	Incorrect UI URL
60	Failed to create payment card

Capture payment

1import {
2  capturePayment,
3  FrameError,
4  ApiError,
5  CapturePaymentError,
6} from '@eonx/payment-elements';
7
8const element = capturePayment({
9  /**
10   * API key with access to the payment API.
11   */
12  apiKey: '-api-key-',
13  /**
14   * Order intent ID
15   */
16  orderIntentId: '-intent-id',
17  /**
18   * Manage to display CVV input in the payment process.
19   * Not required.
20   */
21  isVerificationCodeRequired: true,
22  /**
23   * Include verification code to capture request
24   * Not required.
25   */
26  verificationCode: '000',
27  /**
28   * Attach card to order intent before capture
29   * Not required.
30   */
31  attachCard: {
32    reference: 'HP6C8X3H97',
33    type: 'MastercardCredit',
34    amount: '10000'
35    consumerOwningEntity: 'someOwningEntity',
36    paymentConfig: 'TEST'
37  },
38  onError(error: Error<CapturePaymentError | FrameError | ApiError>) {
39    // Callback when any errors occurring with element
40  },
41  onSuccess(result: OrderIntent) {
42    // Callback when the payment is captured
43  },
44  onVerify({ mount }) {
45    // Callback when we need to mount the UI to handle 3DS.
46    // See MountContainer type
47    mount('#container');
48  },
49});
50
51/**
52 * Element will be automatically disposed when container will be removed from DOM.
53 * Use dispose method if you need to cancel element manually.
54 */
55element.dispose();

Error Codes

Code	Description
10	API key required
11	Payment API URL not found
12	Unhandled API error
20	HTML container required
21	Failed to render payment UI
40	Failed to complete payment
41	Order intent ID has required for capture
42	Failed to retrieve order intent
43	Payment source required
44	Multiple cards are not supported
45	Payment gateway has not supported
46	Failed to load third-party SDK
47	3D Secure verification failed. Please contact your bank.
48	Unable to apply payment for your order

Pay now

1import { payNow } from '@eonx/payment-elements';
2
3const element = payNow({
4  /**
5   * Predefined values: 'light' or 'dark'.
6   * You can pass custom theme created by `createTheme` method.
7   * Non-required field.
8   */
9  theme: 'light',
10  /**
11   * API key with access to the payment API.
12   */
13  apiKey: '-api-key-',
14  /**
15   * HTML container where the payment element will be mounted.
16   */
17  container: 'container-id',
18  /**
19   * IntentId of the order to finalize the payment
20   */
21  orderIndentId: 'xxxxxxx-f6a3-4524-8f5f-df2a7188xxxx',
22  /**
23   * Payment card to capture order intent.
24   * Non-required field.
25   */
26  card: {
27    cardholder: 'Joe Black',
28    number: '4242 4242 4242 4242',
29    expiryMonth: 1,
30    expiryYear: 2039,
31  },
32  /**
33   * Manage to display CVV input in the payment process.
34   * Non-required field.
35   */
36  isVerificationCodeRequired: true,
37  onError(error: Error<CreateCardError | FrameError | ApiError>) {
38    // Callback when any errors occurring with element
39  },
40  onProcess() {
41    // Callback when form submitting.
42  },
43  onMounted() {
44    // The form is ready to display
45  },
46});
47
48/**
49 * Element will be automatically disposed when container will be removed from DOM.
50 * Use dispose method if you need to cancel element manually.
51 */
52element.dispose();

Error Codes

Code	Description
10	API key required
11	Payment API URL not found
12	Unhandled API error
20	HTML container required
21	Failed to render payment UI
40	Failed to complete payment
41	Order intent ID has required for capture
42	Failed to retrieve order intent
43	Payment source required
44	Multiple cards are not supported
45	Payment gateway has not supported
46	Failed to load third-party SDK
47	3D Secure verification failed. Please contact your bank.
48	Unable to apply payment for your order

Void payment

1import {
2  voidPayment,
3  Error,
4  VoidPaymentError,
5  ApiError,
6} from '@eonx/payment-elements';
7
8try {
9  const result: OrderIntent = await voidPayment({
10    /**
11     * API key with access to the payment API.
12     */
13    apiKey: '-your-key-',
14    /**
15     * Order intent ID
16     */
17    orderIntentId: '-intent-id-',
18  });
19} catch (e) {
20  const error: Error<VoidPaymentError | ApiError> = e;
21  // use error
22}

Error Codes

Code	Description
10	API key required
11	Payment API URL not found
12	Unhandled API error
50	Order intent ID has required for void

Types

1type MountContainer = string | HTMLElement;

1export interface OrderIntent {
2  id: string;
3  status: 'pending' | 'voided' | 'captured';
4  order: {
5    id: string;
6    generalStatus: 'completed' | 'failed' | 'processing' | 'refunded';
7    createdAt: string;
8    updatedAt: string;
9  };
10  provider: {
11    id: string;
12    name: string;
13    createdAt: string;
14    updatedAt: string;
15  };
16  destinations: PaymentDestination[];
17  securityTokenRequired: boolean;
18  sources: PaymentSource[];
19  tags: string[];
20  createdAt: string;
21  updatedAt: string;
22  expiresAt: string;
23  feeType: 'provider' | 'source';
24  customer?: {
25    createdAt: string;
26    id: string;
27    updatedAt: string;
28    fullName: string;
29  };
30  description?: string;
31  dueFeeAmount?: string;
32  dueFinalAmount?: string;
33  externalId?: string;
34  statementDescriptor?: string;
35}
36
37export interface PaymentDestination {
38  id: string;
39  amount: string;
40  reference: string;
41  type:
42    | 'BankAccountReceiver'
43    | 'BpayReceiver'
44    | 'Ewallet'
45    | 'ProviderFloat'
46    | 'UnattachedReceiver';
47  createdAt: string;
48  updatedAt: string;
49  description?: string;
50  fixedFeeRate?: string;
51  paymentConfig?: string;
52  percentageFeeRate?: number;
53  statementDescriptor?: string;
54}
55
56export interface PaymentSource {
57  /**
58   * Amount to come from the order source, expressed in the smallest unit of the currency of the order source,
59   * e.g. 500 for AUD 5.00. The amount is exclusive of fees.
60   */
61  id: string;
62  reference: string;
63  type: PaymentMethodType;
64  createdAt: string;
65  updatedAt: string;
66  amount: string;
67  creditLimitAllowed: boolean;
68  feePayer: boolean;
69  gateway: string;
70  consumerOwningEntity?: string;
71  description?: string;
72  percentageFeeRate?: number;
73  paymentConfig?: string;
74  paymentRate?: number;
75  recurringPaymentExternalId?: string;
76  statementDescriptor?: string;
77}
78
79export type PaymentMethodType =
80  | 'AmericanExpressCredit'
81  | 'MastercardCredit'
82  | 'MastercardDebit'
83  | 'MastercardPrepaid'
84  | 'VisaCredit'
85  | 'VisaDebit'
86  | 'VisaPrepaid';

Errors

1interface Error<T> {
2  code: T;
3  message: string;
4  description: string;
5  violations: Record<string, string[]>;
6  data: any;
7  isCritical: boolean;
8  responseStatus?: number;
9}

1export enum ApiError {
2  KeyRequired = 10,
3  UrlRequired = 11,
4  UnhandledError = 12,
5  KeyExpired = 13,
6}

1export enum FrameError {
2  ContainerRequired = 20,
3  MountFailed = 21,
4}

1export enum CapturePaymentError {
2  CaptureFailed = 40,
3  IntentIdRequired = 41,
4  IntentFailed = 42,
5  CardRequired = 43,
6  MultipleCards = 44,
7  UnknownGateway = 45,
8  SdkFailed = 46,
9  SecureFailed = 47,
10  OrderFailed = 48,
11}

1export enum VoidPaymentError {
2  IntentIdRequired = 50,
3}

1export enum CreateCardError {
2  Failed = 60,
3}

Error handling

1import { createPaymentCard, ApiError } from '@eonx/payment-elements';
2
3const element = createPaymentCard({
4  // ...
5  onError(e: Error) {
6    if (e.code === ApiError.KeyExpired) {
7      // For example, reload UI and display notify when API key is expired
8    } else {
9      // handle error
10    }
11  },
12});