@clubessentialholdings/js-elements

v2.1.0

Published

4 months ago

OdinPay JavaScript Elements

0High
0Medium
0Low

OdinPay JavaScript Elements

The JS elements library provides OdinPay customers the means to collect sensitive data from users within their web applications, without the risk of managing such data. Currently the only supported data collection is Bank Account and Credit Card information but this data set will grow over time.

Getting Started

To instantiate OdinPay JS elements follow these steps:

Generate a public token using the Generate Token endpoint and use the generated token to initialize the OdinPay JS elements library.
Define the HTML elements where the JS Elements will be rendered. Each one of these elements needs to have a user defined unique ID that will be used for mapping and injecting the JS elements into your form, for example:

<div id="[user-defined-id-cardInfo]"></div>
<div id="[user-defined-id-postalcode]"></div>
<button id="[user-defined-id-button]">Save Payment Method</button>

Include the library script in the page directly via a script tag (CDN), or via dependencies:

<script src="https://js.odinpay.net"></script>

const OdinPay = require("@clubessentialholdings/js-elements");
// or
import OdinPay from "@clubessentialholdings/js-elements";

Then, add the following code to initialize the library. OdinPay will be defined as a global variable as well as accessible via window.OdinPay.

// CDN
window.addEventListener("load", async () => {
	const odinPayElements = OdinPay("public-token", {
		theme,
		country
	});
});

// via import
const odinPayElements = OdinPay("public-token", {
	theme,
	country
});

Once the library has been initialized and the html elements haven defined, components can be rendered. Below is the example of how you’d render a credit card form with just the required fields:

odinPayElements.createCreditCardForm({
	submitButton: {
		selector: "[user-defined-id-button]",
		callback: (result) => {
			//... your goes code here
		}
	},
	fields: {
		cardInformation: {
			selector: "[user-defined-id-cardInfo]",
			ariaLabel: "testLabel"
		},
		postalCode: {
			selector: "[user-defined-id-postalcode]",
			placeholder: "Postal Code",
			ariaLabel: "testLabel"
		}
	},
	onChangeValidation: (fieldInformation) => {
		handleValidation(fieldInformation, "cardWithPostalCode-errors");
	}
});

API Documentation

INITIALIZER

`OdinPay(token, config)`

Initializes the OdinPay object

PARAMETERS:

METHODS

| Methods | Explanation | | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | createCardForm ({ submitButton, fields, onChangeValidation }) | Renders a credit card form based on the desired configuration. The cardInformation and postalCode fields are required to be able to render a credit card form. | | createBankAccountForm({ submitButton, fields, onChangeValidation }) | Defines the look and feel of the component(s) inputsRenders a bank account form based on the desired configuration. The accountNumber, bankAccountType, routingNumber and name (name on account) fields are required to be able to render a bank account card form. |

PARAMETERS:

Card Example

OdinPay.createCardForm({
	submitButton: {
		selector: "[user-defined-id-submitButton]",
		callback: (result) => {
			handleResponse(result);
		}
	},
	fields: {
		cardInformation: {
			selector: "[user-defined-id-cardInformation]",
			ariaLabel: "testLabel"
		},
		postalCode: {
			selector: "[user-defined-id-postalCode]",
			placeholder: "Postal Code",
			ariaLabel: "testLabel"
		}
	},
	onChangeValidation: (validation) => handleValidation(validation)
});

Bank Account Example

OdinPay(token).createBankAccountForm({
	submitButton: {
		selector: "[user-defined-id-submitButton]",
		callback: (result) => {
			handleResponse(result);
		}
	},
	fields: {
		accountNumber: {
			selector: "[user-defined-id-accountNumber]",
			ariaLabel: "testLabel",
			placeholder: "Account Number"
		},
		routingNumber: {
			selector: "[user-defined-id-routingNumber]",
			placeholder: "Routing Number"
		},
		bankAccountType: {
			selector: "[user-defined-id-bankAccountType]"
		},
		name: {
			selector: "[user-defined-id-nameOnAccount]",
			placeholder: "Name"
		}
	},
	onChangeValidation: (validation) => handleValidation(validation)
});

CONFIG

Is an optional property in OdinPay initialization, allowing additional configurations for theme and country

{
	"theme": {},
	"country": "US"
}

Currently Supported Countries

THEME

An optional object to allow the user to define custom styles for background colors, padding, fonts and pseudo-elements. These will be applied through the theme object rather than through a CSS stylesheet.

Other styling for things such as borders to your container divs should be done in a CSS sheet.

Example theme object:

{
	"fontFamily": "Fira Sans,Droid Sans",
	"fontSize": "16px",
	"::placeholder": {
		"color": "rgb(117, 117, 117)",
		"fontSize": "16px"
	}
}

Allowed CSS Properties in the theme object

backgroundColor
color
fontFamily
fontSize
fontSmooth
fontStyle
fontVariant
fontWeight
lineHeight
letterSpacing
textAlign
padding
textDecoration
textShadow
textTransform

Allowed pseudo-elements in the theme object

:hover
:focus
:read-only
::placeholder
::selection
:disabled

ERROR HANDLING

There are two types of error handling: on change and on submit. Both return the same format of error object to provide a more uniform response for error handling.

On Change

An optional function in the configuration object when using createCardForm or createBankForm. Used to handle field validation errors.

It will return an error object during blur and change events.

Please see the static folder for a fully functional example of onChange validation.


const handleValidation = (fieldInformation) => {
    const {selector, errorCode, fieldName} = fieldInformation;
    //handle validation errors here
}

await op.createCardForm({
  submitButton: {...},
  fields: {...},
  onChangeValidation: (fieldInformation) => {
    handleValidation(fieldInformation);
  }
})

On Submit

This will only trigger when the user clicks the submit button. It returns the submit response.

If there are errors, it will return an array of the same error object as the onChange validation. However, onSubmit can also return backend errors unlike the onChange validation.

Please see static folder for fully functional examples of onSubmit error handling.

await op.createCardForm({
    onChangeValidation: {...},
    fields: {...},
    submitButton: {
        selector: "bankOnly-submit-CA",
        callback: (result) => {
            result?.errors?.forEach((fieldInformation) => {
                handleValidation(fieldInformation);
            });
        }
    }
});

TYPE DEFINITIONS

Submit Button

The configuration object for your form's submit button.

Field

Configuration object for an input field.

PROPERTIES:

Fields Properties

These are the properties that are allowed in the fields list

PROPERTIES:

Submit Response

returned from the submit button's callback.

Payment Method

The payment method object from the submit callback.

Error Object

Returned from both the onChange and onSubmit validation.

Error types:

ERROR CODES:

Demo

Try out different CodePen examples for both card and bank forms:

https://codepen.io/collection/vOYpPa

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

OdinPay JavaScript Elements

Getting Started

API Documentation

INITIALIZER

OdinPay(token, config)

PARAMETERS:

METHODS

PARAMETERS:

Card Example

Bank Account Example

CONFIG

THEME

ERROR HANDLING

On Change

On Submit

TYPE DEFINITIONS

Submit Button

Field

PROPERTIES:

Fields Properties

PROPERTIES:

Submit Response

Payment Method

Error Object

Error types:

ERROR CODES:

Demo

`OdinPay(token, config)`