Guide (React)

Elements are secure embeds that host various payment fields on our servers, ensuring PCI compliance. They are managed through the <ElementsForm /> component, which acts as a provider, offering the necessary context for these elements to function.

To use <ElementsForm />, you must supply a checkoutSecureToken. This token is generated by creating a checkout session through the OpenPay Python SDK. Learn how to create a Checkout Session.

The library provides separate elements for different card details, as well as a combined input for all details in one field:

• <CardNumberElement />: Card number input field.

• <CardExpiryElement />: Card expiry date input field.

• <CardCvcElement />: Card security code input field.

• <CardElement />: A combined input field for card number, expiry, and CVC.

The <ElementsForm /> component offers a variety of 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) => 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: 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: FieldNames, 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: Created or pre-assigned customer's ID.

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

  • message: A string describing the error.

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 <ElementsForm>.

Here are the available field names:

• FieldName.FIRST_NAME

• FieldName.LAST_NAME

• FieldName.EMAIL

• FieldName.ZIP_CODE

• FieldName.CITY

• FieldName.STATE

• FieldName.COUNTRY

• FieldName.ADDRESS

• FieldName.PHONE

• FieldName.PROMOTION_CODE

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

Out of the box, OpenPay elements are unstyled, with a transparent background and text color adapting to the system’s color scheme. However, you can easily customize the appearance of these elements using the styles prop, or by wrapping them inside containers to apply your own custom styling.

Here are some CSS properties you can apply to the elements:

• backgroundColor

• color

• fontFamily

• fontSize

• fontWeight

• margin

• padding

Placeholder Customization:

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

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

See more styling examples here:

Examples