Customization Questions about Checkout

Yes. Although PCI v4 requirements have strict restrictions on payment field customizations, there are some options.

Checkout modal allows you to select a primary color to apply to the Finish and pay button. You can set the color in the Checkout modal data element configuration. In this example, the primary color is set to "red" which is reflected in the button color.

Checkout embedded allows you to select a primary color, font color, and font family in the Checkout embedded data element configuration. In this example:

• Primary color is set to "purple" which is reflected in the button color

• Font color is set to "blue" which is reflected in the unselected button

• Font family is set to "arial" which is reflected in the button text and reCAPTCHA message.

Tip: You can also apply custom-built payment solutions such as DAF Pay or other customizations, such as recurring gift upsells, before or after the new payment section in your form.

The Style field in the Checkout data element allows you to enter a primary color in the checkout modal.

1. Select Fundraising, Donation Management, and All Donation Forms.

2. Edit a donation form on the list.

3. Select Design Donor Screens and Edit the Donation Form screen.

4. On the left, under Arrange the order of the selected data elements, select either Checkout modal or Checkout embedded.

5. Select Save Order and Edit Selected.

6. Enter the color in the Style field, and Preview or Save your changes.

   Checkout modal:

   

   Checkout embedded:

   

Due to the changes for PCI v4 requirements, we can no longer allow custom code in the payments section of a donation form. This means that you must place your custom DAF Pay button in a location outside of the payments section of your donation form.

For example, you can apply the DAF Pay button directly above the forms "Payment Information" section, or place it next to the gift amount button selection.

If your donation form includes a customized Process button, it’s important to ensure it doesn’t interfere with payment processing. Improper customizations can cause donation attempts to fail, and Blackbaud Merchant Services (BBMS) may list these transactions as “Not Processed.”

Why This Happens

Older customizations — such as modal upsells, custom validations, or donor cover logic — often use fake buttons or override the default pstep_finish behavior. These can conflict with the new checkout flow, especially when using digital wallets like Google Pay or PayPal.

Best Practices for Custom Button Handling

Standard Behavior: Use the pstep_finish button for form submission.

Avoid Fake Buttons: Custom buttons (e.g., pstep-custom) that trigger modals or validations can break the submission flow.

Avoid Preventing Default Behavior: Overriding pstep_finish with event.preventDefault() can interfere with checkout and digital wallet flows.

Watch for Code Locations: Custom logic may be in:

• Event listeners

• Page wrappers

• HTML captions

• External JS files (e.g., via FTP)

Risks of Improper Customization

• Breaks multi-step submission flow: Luminate Online and Blackbaud Merchant Services perform a handshake to validate and record gifts. Interference can cause failures.

• Digital wallet incompatibility: Wallets like PayPal and Google Pay have their own flows that may bypass or conflict with custom logic.

• Hard to debug: Custom implementations can require deep analysis of the source and require development tools to identify conflicts.

Steps to Resolve the Issue for Custom Code in the HTML Caption Data Element

1. Determine who can update your code, either someone on your team, a web developer, or Blackbaud Professional Services.

2. Locate and edit your donation form

   1. In Luminate Online, go to Fundraising, Donation Management.

   2. Select the All Donation Forms tab.

   3. Find your form and select Edit under the Actions column.

   4. On the left, select Design Donor Screens.

   5. For Donation Form, select Edit.

   6. On the left, highlight the HTML Caption data element.

   7. Select Save and Edit Selected.

3. Update the “Process” Button Logic. Ensure your form uses the correct pstep_finish button. You can use the following JavaScript to handle Enter key submissions safely:

   document.body.addEventListener("keypress", function(event) {

   if (event.keyCode === 13) {

   event.preventDefault();

   var button = document.getElementById("pstep_finish") ||

   document.getElementById("pstep_next") ||

   document.getElementById("pstep_finish_validate");

   if (button) {

   button.click();

   }

   }

   });

4. Save your changes.

5. Test the form.

6. Try different payment methods (credit card, bank account, Google Pay, PayPal) to ensure compatibility.

7. Publish the form

Note: As of release 25.3.1a, additional logging is available to help identify issues related to button handling and submission flow.