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:
- The
url
param is mandatory and it must be the url provided by the SeQura API. - 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.1/sequra-pci.js"
integrity="sha384-nntbqZYpgUrYyp3BrkXF/1SGmGfgMTPbXGXTdnh4jI2OVqTfhTbC8zeF7h/o45JX"
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