payment-elements-beta v0.0.4

Payment Elements SDK

[toc]

Configuration

import { configurePaymentElements } from 'payment-elements-beta'

configurePaymentElements({
  /**
   * Set it as true if you are working in a test environment 
   **/
  test: true,
  themes: {
    /**
     * Global settings for all themes
     */
    '*': {
      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',
        colorText: '#37474f',
        colorPlaceholder: '#78909c',
        colorInputLabel: '#455a64',
        colorInputBackground: '#fff',
        colorTextLight: 'gray',
        borderRadius: '6px',
        spacing: '10px',
        spacingLabel: '2px',
        inputHeight: '44px',
      },
    },
    /**
     * 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',
      },
    },
  },
})

Create payment card

import { 
  createPaymentCard, 
  ApiError, 
  FrameError, 
  CreateCardError,
  PaymentCardTokenizeResult,
} from 'payment-elements-beta'

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. 
  },
  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()

Result

export 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

Capture payment

import { 
  capturePayment, 
  FrameError, 
  ApiError, 
  CapturePaymentError,
} from 'payment-elements-beta'

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
   */
  isVerificationCodeRequired: true,
  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

Pay now

import { 
  payNow,
} from 'payment-elements-beta'

const element = payNow({
 /**
   * 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',
  number: '5123 4500 0000 0008',
  cvc: '100',
  expiry: '01/2039',
  /**
   * IntentId of the order to finalize the payment
   */
  order: {
    intentId: 'xxxxxxx-f6a3-4524-8f5f-df2a7188xxxx',
  },
  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()

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

Error Codes

Void payment

import { 
  voidPayment, 
  Error, 
  VoidPaymentError,
  ApiError,
} from 'payment-elements-beta'

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

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
}

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

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,
}