@eonx/payment-elements

v1.27.2

Published

16 days ago

- [Configuration](#configuration) - [Create payment card](#create-payment-card) - [Capture payment](#capture-payment) - [Pay now](#pay-now) - [Void payment](#void-payment) - [Types](#types) - [Error handling](#error-handling)

Downloads

1,630

0High
0Medium
0Low

kieron_eonx

natepage

payment sdk credit debit card

Payment Elements SDK

Getting started

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

Configuration

import { configurePaymentElements } from '@eonx/payment-elements';

configurePaymentElements({
  /**
   * Set it as true if you are working in a test environment
   **/
  test: true,
  /**
   * Change input behavior to floating label
   **/
  inputFloatLabel: true,
  /**
   * If true the expiry date will be in MM/YYYY, else MM/YY
   **/
  expiryFullYear: true,
  themes: {
    /**
     * Global settings for all themes
     */
    base: {
      fonts: [
        {
          css: 'https://fonts.googleapis.com/css2?family=Lato:wght@400;700&family=Roboto&display=swap',
        },
      ],
      styles: {
        fontFamily: 'Lato',
        fontSizeBase: '12px',
        fontSizeSmall: '15px',
        colorPrimary: '#6366f1',
        colorBorder: '#e0e0e0',
        colorDanger: '#e53935',
        colorSuccess: '#22c55e',
        colorText: '#37474f',
        colorPlaceholder: '#78909c',
        colorDivider: '#e5e7eb',
        colorInputLabel: '#455a64',
        colorInputBackground: '#fff',
        colorTextLight: 'gray',
        borderRadius: '6px',
        spacing: '10px',
        spacingLabel: '2px',
        inputHeight: '44px',
        buttonHeight: '46px',
      },
    },
    /**
     * Global settings will be inherited and overrode here
     */
    custom: {
      fonts: [
        {
          family: 'Poppins',
          weight: '400',
          display: 'swap',
          src: `url(${window.location.origin}/fonts/poppins-regular.woff2)`,
        },
      ],
      styles: {
        fontFamily: 'Poppins',
        fontSizeBase: '16px',
      },
    },
  },
});

You may update the configuration at the runtime.

configurePaymentElements({
  theme: 'dark',
});

Create payment card

import {
  createPaymentCard,
  ApiError,
  FrameError,
  CreateCardError,
  PaymentCardTokenizeResult,
} from '@eonx/payment-elements';

const element = createPaymentCard({
  /**
   * Predefined values: 'light' or 'dark'.
   * You can pass custom theme created by `createTheme` method.
   */
  theme: 'light',
  /**
   * API key with access to the payment API.
   */
  apiKey: '-api-key-',
  /**
   * HTML container where the payment element will be mounted.
   */
  container: 'container-id',
  /**
   * Initial value for the cardholder field
   */
  cardholder: 'Joe Black',
  onSuccess(response: PaymentCardTokenizeResult) {
    // Callback when credit card created
  },
  onError(error: Error<CreateCardError | FrameError | ApiError>) {
    // Callback when any errors occurring with element
  },
  onProcess() {
    // Callback when form submitting.
  },
  onChange(event: {
    data: CardDetails;
    isValid: boolean;
    isReadyToSubmit: boolean;
  }) {
    // Form values changed
  },
  onMounted() {
    // The form is ready to display
  },
});

/**
 * Element will be automatically disposed when container will be removed from DOM.
 * Use dispose method if you need to cancel element manually.
 */
element.dispose();

/**
 * Send submit event to form
 */
element.submit();

/**
 * Pre-fill form. Partial values is allowed.
 */
element.prefill({
  cardholder: 'Test User',
  number: '5123450000000008',
  cvc: '100',
  expiryMonth: 1,
  expiryYear: 2039,
});

element.prefill({
  cardholder: 'Test User',
});

/**
 * Submit on the form will not be triggered
 */
element.disableSubmit();

/**
 * Cancel form disabling by previous method.
 */
element.enableSubmit();

/**
 * Change theme after the element has been created.
 */
element.changeTheme('dark');

Types

interface CardDetails {
  cardholder: string;
  number: string;
  cvc: string;
  expiryMonth: number;
  expiryYear: number;
}

Result

interface PaymentCardTokenizeResult {
  cardholder: string;
  createdAt: string;
  currency: {
    id: string;
    name: string;
    createdAt: string;
    updatedAt: string;
  };
  customer: {
    createdAt: string;
    fullName: string;
    id: string;
    updatedAt: string;
  };
  description: string;
  expiryMonth: number;
  expiryYear: number;
  hash: string;
  id: string;
  pan: string;
  paymentMethodType: PaymentMethodType;
  provider: {
    name: string;
    id: string;
    createdAt: string;
    updatedAt: string;
  };
  reference: string;
  status: 'inactive' | 'active';
  updatedAt: string;
  verified: boolean;
}

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

import {
  capturePayment,
  FrameError,
  ApiError,
  CapturePaymentError,
} from '@eonx/payment-elements';

const element = capturePayment({
  /**
   * API key with access to the payment API.
   */
  apiKey: '-api-key-',
  /**
   * Order intent ID
   */
  orderIntentId: '-intent-id',
  /**
   * Manage to display CVV input in the payment process.
   * Not required.
   */
  isVerificationCodeRequired: true,
  /**
   * Include verification code to capture request
   * Not required.
   */
  verificationCode: '000',
  /**
   * Attach card to order intent before capture
   * Not required.
   */
  attachCard: {
    reference: 'HP6C8X3H97',
    type: 'MastercardCredit',
    amount: '10000'
    consumerOwningEntity: 'someOwningEntity',
    paymentConfig: 'TEST'
  },
  onError(error: Error<CapturePaymentError | FrameError | ApiError>) {
    // Callback when any errors occurring with element
  },
  onSuccess(result: OrderIntent) {
    // Callback when the payment is captured
  },
  onVerify({ mount }) {
    // Callback when we need to mount the UI to handle 3DS.
    // See MountContainer type
    mount('#container');
  },
});

/**
 * Element will be automatically disposed when container will be removed from DOM.
 * Use dispose method if you need to cancel element manually.
 */
element.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

import { payNow } from '@eonx/payment-elements';

const element = payNow({
  /**
   * Predefined values: 'light' or 'dark'.
   * You can pass custom theme created by `createTheme` method.
   * Non-required field.
   */
  theme: 'light',
  /**
   * API key with access to the payment API.
   */
  apiKey: '-api-key-',
  /**
   * HTML container where the payment element will be mounted.
   */
  container: 'container-id',
  /**
   * IntentId of the order to finalize the payment
   */
  orderIndentId: 'xxxxxxx-f6a3-4524-8f5f-df2a7188xxxx',
  /**
   * Payment card to capture order intent.
   * Non-required field.
   */
  card: {
    cardholder: 'Joe Black',
    number: '4242 4242 4242 4242',
    expiryMonth: 1,
    expiryYear: 2039,
  },
  /**
   * Manage to display CVV input in the payment process.
   * Non-required field.
   */
  isVerificationCodeRequired: true,
  onError(error: Error<CreateCardError | FrameError | ApiError>) {
    // Callback when any errors occurring with element
  },
  onProcess() {
    // Callback when form submitting.
  },
  onMounted() {
    // The form is ready to display
  },
});

/**
 * Element will be automatically disposed when container will be removed from DOM.
 * Use dispose method if you need to cancel element manually.
 */
element.dispose();

Error Codes

Void payment

import {
  voidPayment,
  Error,
  VoidPaymentError,
  ApiError,
} from '@eonx/payment-elements';

try {
  const result: OrderIntent = await voidPayment({
    /**
     * API key with access to the payment API.
     */
    apiKey: '-your-key-',
    /**
     * Order intent ID
     */
    orderIntentId: '-intent-id-',
  });
} catch (e) {
  const error: Error<VoidPaymentError | ApiError> = e;
  // use error
}

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

type MountContainer = string | HTMLElement;

export interface OrderIntent {
  id: string;
  status: 'pending' | 'voided' | 'captured';
  order: {
    id: string;
    generalStatus: 'completed' | 'failed' | 'processing' | 'refunded';
    createdAt: string;
    updatedAt: string;
  };
  provider: {
    id: string;
    name: string;
    createdAt: string;
    updatedAt: string;
  };
  destinations: PaymentDestination[];
  securityTokenRequired: boolean;
  sources: PaymentSource[];
  tags: string[];
  createdAt: string;
  updatedAt: string;
  expiresAt: string;
  feeType: 'provider' | 'source';
  customer?: {
    createdAt: string;
    id: string;
    updatedAt: string;
    fullName: string;
  };
  description?: string;
  dueFeeAmount?: string;
  dueFinalAmount?: string;
  externalId?: string;
  statementDescriptor?: string;
}

export interface PaymentDestination {
  id: string;
  amount: string;
  reference: string;
  type:
    | 'BankAccountReceiver'
    | 'BpayReceiver'
    | 'Ewallet'
    | 'ProviderFloat'
    | 'UnattachedReceiver';
  createdAt: string;
  updatedAt: string;
  description?: string;
  fixedFeeRate?: string;
  paymentConfig?: string;
  percentageFeeRate?: number;
  statementDescriptor?: string;
}

export interface PaymentSource {
  /**
   * Amount to come from the order source, expressed in the smallest unit of the currency of the order source,
   * e.g. 500 for AUD 5.00. The amount is exclusive of fees.
   */
  id: string;
  reference: string;
  type: PaymentMethodType;
  createdAt: string;
  updatedAt: string;
  amount: string;
  creditLimitAllowed: boolean;
  feePayer: boolean;
  gateway: string;
  consumerOwningEntity?: string;
  description?: string;
  percentageFeeRate?: number;
  paymentConfig?: string;
  paymentRate?: number;
  recurringPaymentExternalId?: string;
  statementDescriptor?: string;
}

export type PaymentMethodType =
  | 'AmericanExpressCredit'
  | 'MastercardCredit'
  | 'MastercardDebit'
  | 'MastercardPrepaid'
  | 'VisaCredit'
  | 'VisaDebit'
  | 'VisaPrepaid';

Errors

interface Error<T> {
  code: T;
  message: string;
  description: string;
  violations: Record<string, string[]>;
  data: any;
  isCritical: boolean;
  responseStatus?: number;
}

export enum ApiError {
  KeyRequired = 10,
  UrlRequired = 11,
  UnhandledError = 12,
  KeyExpired = 13,
}

export enum FrameError {
  ContainerRequired = 20,
  MountFailed = 21,
}

export enum CapturePaymentError {
  CaptureFailed = 40,
  IntentIdRequired = 41,
  IntentFailed = 42,
  CardRequired = 43,
  MultipleCards = 44,
  UnknownGateway = 45,
  SdkFailed = 46,
  SecureFailed = 47,
  OrderFailed = 48,
}

export enum VoidPaymentError {
  IntentIdRequired = 50,
}

export enum CreateCardError {
  Failed = 60,
}

Error handling

import { createPaymentCard, ApiError } from '@eonx/payment-elements';

const element = createPaymentCard({
  // ...
  onError(e: Error) {
    if (e.code === ApiError.KeyExpired) {
      // For example, reload UI and display notify when API key is expired
    } else {
      // handle error
    }
  },
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Payment Elements SDK

Getting started

Configuration

Create payment card

Types

Result

Error Codes

Capture payment

Error Codes

Pay now

Error Codes

Void payment

Error Codes

Types

Errors

Error handling