@pekopay/web

This is a PekoPay pure JavaScript library for securely collecting payment information and processing transactions. It streamlines integration with the Pekopay platform, providing built-in validation, error handling, and submission of the payment method to the PekoPay platform for processing.

How to use

1. Create an HTML element where the credit card will be rendered

<div id="credit-card-form-container"></div>

2. Preload the PekoPay web CDN sdk

<link as="script" rel="modulepreload" href="https://cdn.jsdelivr.net/npm/@pekopay/web@<version>/dist/index.js" />

If you are using React and NPM packages, install @pekopay/web library and import the module in your code.

3. After the @pekopay/web library bundle has been loaded, add another script tag to initialize the credit card form and execute the mount to render the form.

  <script type="module">
    import { PekoCheckoutForm } from 'https://cdn.jsdelivr.net/npm/@pekopay/web@<version>/dist/index.js';

    /**
     * You will need to generate a payment token using the PekoPay API
     */
    const paymentToken = '<%= paymentToken %>'; // e.g using payment token from backend using ejs templating
    document.addEventListener('DOMContentLoaded', function () {
      const checkoutFormContainer = document.getElementById('credit-card-form-container');
      const form = PekoCheckoutForm.initialize({
        sessionToken: paymentToken,
        environment: 'sandbox', // Change to 'production' in production
        container: checkoutFormContainer,
        height: 160,
        width: 300,
        onFormFieldStateChange: (data) => {
            // Handle and react to any form fields changes
          console.log('Form field state changed:', data);
        },
        onLoadError: (error) => {
          console.error('Form load error:', error);
        },
        completeTransaction: async (data) => {
          console.log('Transaction completed:', data);
          const paymentToken = data.sessionToken;
          // Build credit card details object
          const selectedCard = {
            cardLastFourDigits: data.cardData.last4Digits,
            cardType: data.cardData.cardType,
          };
        },
        sessionTokenProvider: async () => {
            /**
             * This function is called when the current payment token expires.
             * Make an API request to fetch a new payment token and return it
             */

            const response = await fetch('<your custom pekopay api wrapper endpoint to get a new token >');

            const { token } = await response.json();

            return token;
        } 
      });

      // RENDER/MOUNT the form in the provided container
      form.mount();

      document.getElementById('pay-button').addEventListener('click', () => {
        form.submitFormFields();
      });
    });
  </script>

Credit card form configuration options

| Option | Type | Description | Required | Default | |--------------------------|------------|-----------------------------------------------------------------------------------------------|----------|-------------| | sessionToken | string | Token generated from PekoPay API for the payment session. Payment token expire in 60 minutes and you need to provide sessionTokenProvider to refresh the token | Yes | - | | environment | string | Environment to use: 'sandbox' or 'production'. | Yes | 'sandbox' | | container | Element | DOM element where the form will be rendered. | Yes | - | | height | number | Height of the form in pixels. | No | 160 | | width | number | Width of the form in pixels. | No | 300 | | onFormFieldStateChange | function | Callback for form field changes. Receives field state data. | No | - | | onLoadError | function | Callback for handling form load errors. Receives error object. | No | - | | completeTransaction | function | Always use the new token provided by this callback to complete your transaction. This callback fires when the payment method (credit card) has been successfully associated with the session. Do not use the initial provided token, as it might be replaced with this fresh token if it has expired. | Yes | - | | sessionTokenProvider | function | A callback that fetches a new payment token from the API. This callback is important when you need to automatically refresh the payment token | No | - |

Completing a payment

To complete a payment, trigger the submitFormFields method (for example, when the user clicks the pay button). Once the form is successfully submitted, the completeTransaction callback will be invoked with the session token and card details. You can then use this session token to make a payment request via the Pekopay invoicing transactions or subscription API, securely associating the collected card information with the transaction or subscription.