Sequra PCI card form integration library

📖 Overview 📖

This library allows to integrate a card payment form

⚙️ Components summary ⚙️

Main components for this service or links to the docs explaining them.

📊 Observability and dashboards 📊

Links to the Grafana business and tech related dashboards.

🔌 System dependencies 🔌

DB engine, cache tooling, job queues, cache servers, search engines, etc.

👩‍💻 Development environment instructions 👩‍💻

How to get your local environment ready to start working.

🚧 How to run the test suite 🚧

How to run the tests

🚀 Use instructions 🚀

API

Config initialization

  SequraPCI.paymentForm({
    url: "https://sequra-provided-url-to-pci-env",
    styles: { marginBottom: "10px" },
    className: 'my-class',
    onCardDataFulfilled: () => { ... },
    onFormErrors:        () => { ... },
    onFormSubmitted:     () => { ... },
    onScaRequired:       () => { ... },
    onScaLoaded:         () => { ... },
    onScaClosed:         () => { ... },
    onPaymentFailed:     ({ error }) => { ... },
    onPaymentSuccessful: () => { ... },
    onLoad:              () => { ... },
  })

Notes:

1. The url param is mandatory and it must be the url provided by the SeQura API.
2. Any callback function param is optional.

Callbacks description

callback	description
onCardDataFulfilled	Called when all the fields in the card form are filled. Useful if the pay button is outside the PCI iframe and want to control the enabled property.
onFormErrors	Called when the form has errors.
onFormSubmitted	Called when the form has been submitted.
onScaRequired	Called when the payment requires a SCA.
onScaLoaded	Called when the SCA iframe has been loaded.
onScaClosed	Called when the SCA iframe has been closed.
onPaymentFailed	Called when a payment has failed. It includes the error type as a parameter.
onPaymentSuccessful	Called when a payment has succeeded.
onLoad	Called when the iframe is first loaded

Mounting

Once the payment form has been initialized, it has to be mounted in the DOM, for example, inside a given div container:

<div id="card_form"></div>

SequraPCI.paymentForm({ ... }).mount("card_form")

For payments with a reused card, the card form should not be shown, then the mount should receive a hidden param.

SequraPCI.paymentForm({ ... }).mount("card_form", { hidden: true })

Note: in this case (payments with a token form), the iframe is auto submitted when is loaded.

Customization

You can pass custom styles that will override base styles defined for the iframe container:

SequraPCI.paymentForm({ styles: { width: "300px" }, ...otherProps }).mount("card_form")

A specific css class can also be passed to customize the iframe with css rules defined in the host html.

SequraPCI.paymentForm({ className: 'payment-form', ...otherProps }).mount("card_form")

Actions

Given a mounted card form iframe:

const paymentForm = SequraPCI.paymentForm({ ... }).mount("card_form")

You can programmatically submit the form:

paymentForm.submitForm()

You can programmatically check/uncheck the permissions checkbox:

paymentForm.setPermissionValue(true)  // checked
paymentForm.setPermissionValue(false) // unchecked

You can remove event listeners (stop listening for iframe post messages):

paymentForm.unbind()

Browser usage

<script
  type="text/javascript"
  src="https://mufasa.sequracdn.com/v1.2.2/sequra-pci.js"
  integrity="sha384-rEujQrBtgDq88sDwTHhsVHHYfyqxP6luE1GbBeTKkJ5EBTIFVkCfTValLYhGr/Sl"
  crossorigin="anonymous">
</script>

This will expose the SequraPCI global var.

NPM package usage

Create a .npmrc file with the following contents:

@sequra:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then, you can add it to your package.json:

yarn add @sequra/mufasa-js-sdk

import SequraPCI from "@sequra/mufasa-js-sdk"; // es6 native
const SequraPCI = require("@sequra/mufasa-js-sdk"); // commonjs