Guide (.js)

Elements are secure embeds that host various payment fields on our servers, ensuring PCI compliance.

You can initialize the form using const openPayForm = new OpenPayForm({ checkoutSecureToken, ...optionalConfigurations })

This checkoutSecureToken token is generated by creating a checkout session through the OpenPay Python/Typescript SDK in the backend. Learn how to create a Checkout Session.

Form target (optional)Copied!

This is the render scope of the form, defaults to document.body . You can specify the query selector string of the container to which the OpenPayForm have to be rendered. Please note that if you specified a container, the payment elements and billing information inputs are also need to be rendered inside the container.

ElementsCopied!

The library provides separate elements for different card details, as well as a combined input for all details in one field. You can create the payment card elements via form instance and render them to your desired container via form instance.

const cardElement = openPayForm.createElement('card', options);
cardElement.mount('#card-element');

 
const cardNumberElement = openPayForm.createElement('card-number', options);
const cardExpiryElement = openPayForm.createElement('card-expiry', options);
const cardCvcElement = openPayForm.createElement('card-cvc', options);
cardNumberElement.mount('#card-number-element');
cardExpiryElement.mount('#card-expiry-element');
cardCvcElement.mount('#card-cvc-element');

The OpenPayForm constructor accepts various callback functions to handle user interactions, errors, and form state changes. These callbacks can be customized to tailor the checkout experience.

• onFocus?: (elementId: string) => void
  Triggered when a form element gains focus.
  Parameters:

  • elementId: The ID of the element that gained focus.

• onBlur?: (elementId: string) => void
  Triggered when a form element loses focus.
  Parameters:

• elementId: The ID of the element that lost focus.

• onChange?: (elementId: string, field: AllFieldNames, errors?: string[]) => void
  Triggered when a form element's value changes.
  Parameters:

  • elementId: The ID of the element whose value changed.

• onLoad?: (totalAmountAtoms?: number, currency?: string) => void
  Triggered when the form is successfully loaded.
  Parameters:

  • totalAmountAtoms: (Optional) The total amount to be processed in atomic units (usually the smallest unit of currency).

  • currency: (Optional) The currency code for the transaction.

• onLoadError?: (message: string) => void
  Triggered if there is an error loading the form.
  Parameters:

  • message: A string describing the error.

• onValidationError?: (field: AllFieldNames, errors: string[], elementId?: string) => void
  Triggered when there is a validation error.
  Parameters:

  • field: The field with a validation issue.

  • errors: An array of error messages.

  • elementId: (Optional) The ID of the element where the error occurred.

• onCheckoutStarted?: () => void
  Triggered when the checkout process starts.

• onCheckoutSuccess?: (invoiceUrls: string[], subscriptionIds: string[], customerId: string) => void
  Triggered upon a successful checkout.
  Parameters:

  • invoiceUrls: Array of invoice URLs.

  • subscriptionIds: Array of subscription IDs.

  • customerId: The customer's ID.

• onCheckoutError?: (message: string) => void
  Triggered when an error occurs during checkout.
  Parameters:

  • message: A string describing the error.

• onPaymentRequestLoad?: (paymentRequests: Record<'apple_pay' | 'google_pay', PaymentRequestStatus>) => void
  Triggered when payment request methods (Apple Pay / Google Pay) are loaded.
  Parameters:

  • paymentRequests: An object containing the status of Apple Pay and Google Pay.

To proceed with checkout, customer billing information is required. While OpenPay.js allows you to implement these fields in your own way, it is important to include the data-opid attribute with the predefined field names. This ensures OpenPay can access and process these fields correctly.

All billing information fields should be rendered within the same target container as the OpenPayForm.

Here are the available field names:

• FieldName.FIRST_NAME

• FieldName.LAST_NAME

• FieldName.EMAIL

• FieldName.ZIP_CODE

• FieldName.COUNTRY

• FieldName.PROMOTION_CODE

By managing the input fields yourself, you gain full control over validation, styling, and autofill functionality.

You can customize the appearance of OpenPay elements by passing a styles object when creating an element. Here are some CSS properties you can apply:

• backgroundColor

• color

• fontFamily

• fontSize

• fontWeight

• margin

• padding

Example:

const cardElement = openPayForm.createElement('card', {
	styles: {
		color: '#32325d',
		fontSize: '16px',
  }
});

Placeholder customization:Copied!

• For individual card elements, the placeholder accepts a string value.

• For the combined card element, the placeholder accepts an object with specific placeholders for card number, expiry, and CVC.
  placeholder : string | { cardNumber: string, expiry: string, cvc: string }

• Placeholder can be styled via placeholderStyle prop. It supports the following type to style placeholder to specific needs.
  placeholderStyle : { color?: string, fontSize?: string, fontWeight?: string, fontFamily?: string, letterSpacing: OptionalString, lineHeight: OptionalString, }

Example:

const cardElement = openPayForm.createElement('card', {
	styles: {
		placeholder: {
      cvc: "Security code"
    }
  }
});