@zeply-ou/payments-web-components

Zeply's main package as payments solution is built in React 18.2.0.

For users having their application built using another framework, e.g Angular, Vue or for version incompatibility issues with React, we provide this helper package which wraps our main package and exposes it as a web component, which will work regardless the framework or version of users application.

Installation

Install it with NPM / YARN

npm install @zeply-ou/payments-web-components

or:

yarn add @zeply-ou/payments-web-components

Documentation

Visit the official Zeply developer site for more information about integrating this package into your website.

Usage

This is an example of how to integrate zeply's payments solution as web components into your React or any other web application.

import React from 'react';
import ReactDOM from 'react-dom';
import {
    PaymentEvent,
    PaymentEventType,
    PaymentGatewayEnvType,
    TransactionTokenType,
    ZPCTheme
} from "@zeply-ou/payments-web-components";

const App = () => {
   /**
    * You need to provide a valid token value 
    * based on the environment and the transaction type.
    **/
    const token = '[RAW JWT TOKEN]',

    const theme: ZPCTheme = {
        background: '#FFFFFF',
        primary: '#000000',
        text: '#000000',
        success: '#25AE88',
        error: '#D75A4A',
        buttonsMode: 'black'
    };
     
    return (
        <zeply-pay-connect 
            transaction_token={token} 
            transaction_type={TransactionTokenType.PAYIN}
            environment={PaymentGatewayEnvType.DEV}
            locale={PaymentGatewaySupportedLanguages.EN}
            theme={JSON.stringify(theme)}
        />
    );
};

ReactDOM.render(<App/>, document.getElementById('root'));

Callbacks

Below is a React code snippet showing how to listen and add your own custom logic based on the variety of values of the paymentEvent variable, using window event listeners.

import React, { useContext, useEffect } from 'react'; 
import { PaymentEvent, ZEPLY_PAY_CONNECT_EVENT } from "@zeply-ou/payments-web-components"

 useEffect(() => {
    const customEventListener =
      (event: CustomEventInit<PaymentEvent>) => {
      switch (event.detail?.type) {
        case PaymentEvenType.INITIATING:
          // custom logic you may add while the ZPC is initiating
          // useful for adding your own custom loader perhaps
          break;
        case PaymentEventType.IDLE:
          // custom logic you may add while the ZPC has been loaded
          // useful for removing your own loader perhaps
          break;
        case PaymentEventType.PAYMENT_SUBMITTED:
          // custom on payment submitted logic
          break;
        case PaymentEventType.PAYMENT_SUCCESS:
          // custom on payment success logic
          break;
        case PaymentEventType.PAYMENT_FAILED:
          // custom on payment fail logic
          break;
        case PaymentEventType.PAYMENT_ERROR:
          // custom on payment error logic
          break;
        case PaymentEventType.PAYMENT_CANCELED:
          // custom on payment cancel logic
          break;
        case PaymentEventType.PAYOUT_SUBMITTED:
          // custom on payout submitted logic
          break;
        case PaymentEventType.PAYOUT_FAILED:
          // custom on payout fail logic
          break;
        case PaymentEventType.PAYOUT_CANCELED:
          // custom on payout cancel logic
          break;
        case PaymentEventType.PAYOUT_ERROR:
          // custom on payout error logic
          break;
        case PaymentEventType.APPLE_PAY_CANCELED:
          // custom on payment apple pay cancelled logic
          // applicable only for apple pay payments
          break;
        case PaymentEventType.GOOGLE_PAY_CANCELED:
          // custom on payment google pay cancelled logic
          // applicable only for google pay payments
          break;
        {/* and so on.. */}
      }
    };

    window.addEventListener(ZEPLY_PAY_CONNECT_EVENT, customEventListener);

    return () => {
      window.removeEventListener(ZEPLY_PAY_CONNECT_EVENT, customEventListener);
    };
  }, []);

Normally as you are integrating with our all in one solution you won't care to add your own custom logic in most of those events.

Usually for these cases the most important ones that you may want to listen are the

• PAYMENT_CANCELED
• PAYMENT_CLOSED
• PAYOUT_CANCELED
• PAYOUT_CLOSED

Of course you are eligible to listen to all type of event if desire.

Options

| Option | Description | Type | Required | | -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------ | | transaction_token | The raw jwt value of the token related to either payins or payouts. | string | true | | transaction_type | The type of transaction. | TransactionTokenType | true |
| environment | This should be one of the 3 Zeply environments in addition with a local environment. | PaymentGatewayEnvType | true | | locale | One of zeply pay connect supported languages. | PaymentGatewaySupportedLanguages | true | | debug | Allows zpc logs for debugging purposes | boolean | false | | theme | The theme of the payment gateway | string (Must be the JSON stringified format of the ZPCTheme type) | false |

Interfaces

TransactionTokenType

enum TransactionTokenType {
  PAYIN = 'PAYIN',
  PAYOUT = 'PAYOUT'
}

PaymentGatewayEnvType

enum PaymentGatewayEnvType {
  /**
   * LOCAL env is used for local development purposes only
   * and only used along with proxy configuration.
   */
  LOCAL = '/',
  DEV = 'https://dev-payments.zeply.com',
  STG = 'https://stg-payments.zeply.com',
  PROD = 'https://payments.zeply.com'
}

PaymentGatewaySupportedLanguages

enum PaymentGatewaySupportedLanguages {
  EN = 'en',
  ET = 'et',
  ES = 'es',
  FR = 'fr',
  DE = 'de',
  NL = 'nl',
  PT = 'pt'
}

ZPCTheme

type ButtonsMode = 'white' | 'black';

type ZPCTheme = {
  background: string;
  primary: string;
  text: string;
  success: string;
  error: string;
  buttonsMode: ButtonsMode;
};

PaymentEvent

interface PaymentEvent {
  type: PaymentEventType;
  details?: string;
  code?: HttpStatusCode;
}