Checkout FAQ
Updated February 20, 2025
To comply with the new PCI 4.0 (Payment Card Industry) standards, all credit and debit card transactions must be configured to use the new checkout experience. This requires updating your donation forms and payment processing to meet the new requirements before March 2025.
Note: ATTENTION: Starting March 18, Blackbaud will begin auditing all donation forms for PCI compliance. Forms not updated to use either the embedded or modal checkout element will be automatically updated with the checkout modal, which could potentially cause layout changes and impact processing. API forms cannot automatically update, so you must take action to manually update API forms ahead of breaking changes. See Auto Migration FAQs.
Select a category of frequently asked questions:
Note: Canadian currency support is available. To enable this support, upgrade your Participant Center. No further action is necessary.
Tip: Feb 4: Register for a live workshop webinar to walk through these changes. eLearnings are also available at Level Up with Luminate Online.
How do I get started?
Existing Blackbaud Merchant Services accounts will complete these steps.
See Update your Checkout Experience for Donation Forms for detailed help.
First, create a new merchant account. In Setup, Payment Capabilities, Merchant Accounts, select Create Account. In Blackbaud Merchant Services Checkout Account, select an account appended with "Checkout."
![]()
Add either the Checkout modal or Checkout embedded to existing forms. (New forms automatically include the modal element.)
![]()
Edit your campaign to use the new checkout merchant account from step 1.
Note: If your existing campaign used a merchant account that was configured with a gateway to support Legacy Blackbaud Checkout, either create a new campaign or use a temporary merchant account.
![]()
About the new checkout

Tip: Register for a Checkout for Luminate Online workshop for a live walk through of these changes.
The new checkout experience is a combination of new merchant account settings and new form data elements that together provide a dynamic, secure, and PCI v4-compliant payment transaction for your donation forms. These updates require a Blackbaud Payment Services account to process and disburse credit and debit card payments.
In addition to credit and debit card, direct debit, and offline payments, the new experience also includes Apple Pay, Google Pay, PayPal, and Venmo digital wallets. We continue to support sustaining (recurring) payments, designated giving, giving levels, tributes, and premium fraud management.
You can use your current Blackbaud Payment Services and Blackbaud Merchant Services accounts. If you need to create accounts, see Getting Started with Blackbaud Merchant Services. Whether you are using new or existing accounts, you need to configure Payment Capabilities in Luminate Online.
Checkout is offered in two versions, modal and embedded. Checkout modal is an iFrame window that surfaces when the supporter is ready to make a payment. Checkout embedded is integrated into your form design.
Warning: Luminate Online will no longer support direct credit and debit card payment processing through Payflow Pro, iATS, and CyberSource payment gateways after January 31, 2025. See End of Support date for directly-connected payment gateways through Luminate Online.

Both the Checkout modal and Checkout embedded elements are available now for you to add to your donation forms.
Designing and implementing new options and improvements will continue even after March 2025.
Note: All active forms must use the new checkout experience for transactions when the new PCI v4 standards take effect in March 2025.

-
Centrally Managed Payment Methods: Every payment type you accept is available under one merchant account. A single account for direct debit, credit and debit cards, and digital wallets makes management easy and efficient.
-
Centrally Managed Payment Processing: End-to-end donation flow from checkout to disbursement is available when using Blackbaud Merchant Services merchant accounts with the new checkout experience.
-
More Payment Options: Checkout supports a wide range of payment methods, including Apple Pay, Google Pay, PayPal, Venmo, direct debit, and credit and debit cards.
Note: Checkout currently supports single transactions with PayPal. Support for recurring PayPal transactions is coming soon. Currently, Venmo only supports USD and single transaction processing.
-
Improved Form Design: Forms are responsive and mobile-first. Get a modern and intuitive interface with either the embedded or modal checkout data element.
-
No Downtime: Collect more with zero downtime.
-
Optimized Payment Capture: More payment methods equal more choice, which translates to higher conversion rates raising your revenue. Blackbaud continually runs A/B tests to improve these conversion rates and optimize the donor experience.
-
Reduced Processing Fees: Donor Cover and Complete Cover are coming soon to the new checkout experience!
-
Secure By Design: Checkout adheres to the highest standards of payment security, being fully PCI-compliant. This ensures that all payment transactions processed meet rigorous security protocols, including encryption, tokenization, and secure data handling practices, and premium fraud management.
Auto-compliance migration on March 18

Starting March 18, Blackbaud will systematically audit all Luminate Online and TeamRaiser donation forms using an auto-compliance script to ensure full adherence to the new PCI requirements.
If non-compliant PCI settings are detected on standard donation forms, the script will autocorrect them by adding the new Checkout Merchant Account (if not already added) and the Modal to the form, which may result in layout changes. While we aim to minimize technical disruptions, please be aware that this script may inadvertently affect some donation forms' payment processing.
Note: To exclude a form from the auto-compliance script, update it for checkout before March 18. Forms already configured with the new checkout are PCI compliant and won't be affected by the script. You can still work on any form even after the script runs.
To avoid any issues, we strongly recommend updating your donation forms using the support resources below before the March 18 deadline. Waiting could cause unexpected payment processing problems.

Warning: Breaking changes are coming to coming to payment processing APIs after March 18.
If your form uses APIs for online credit and debit card transactions via Luminate Online, upcoming PCI standards require updates to API methods, parameters, and shadow forms. There will not be automatic updates made to API-based donation forms; however, the previous APIs will cease to function, blocking the forms. These forms require manual updates as these are BREAKING CHANGES.
Warning: Before March 2025, update your forms to use the new checkout API methods.
Previous method | New method |
---|---|
addGift (TeamRaiser) | addGiftCheckout (TeamRaiser) |
donate | donateCheckout |
offlineOrganizationGift | offlineOrganizationGiftCheckout |
updateRecurringBankAccountInfo | updateRecurringCheckoutPaymentInfo (Coming in 25.2) |
updateRecurringCreditCardInfo | updateRecurringCreditCardInfo (Coming in 25.2) |
Additionally, in TeamRaiser, processRegistration will only process transactions that use a transaction token after March 2025. That is, credit card numbers will no longer flow through the method.
APIs that are being deprecated after March 18:
-
addGift (TeamRaiser)
For further information, please review the Checkout API documentation.

For Canadian customers processing ACH transactions through iATS, please use a separate donation form from the one used for credit cards processed through Blackbaud Merchant Services. We are working on a consolidated payment solution for credit cards and Canadian ACH on the same form, which will be available in 2025.

PCI compliance applies to all customers and Blackbaud, so to protect credit card processing for everyone, Blackbaud must ensure that all credit card processing is compliant by the deadline.

Blackbaud will review every part of Luminate Online and TeamRaiser that touches credit card processing to ensure that the appropriate merchant account has been established and that a PCI-compliant checkout data element has been added. For areas that are not updated, the script will select a checkout merchant account and enable the Checkout modal data element.
Note: The Auto-Compliance Script will NOT update API forms. They must be adjusted manually to ensure they continue working appropriately.

Yes, all development sites will also have the script run.

March 18, 2025 is the deadline.
This is the date to ensure you have your credit card processing pointed to the appropriate merchant account and have either the modal or embedded PCI-compliant data element enabled. If you have completed this step, the script will SKIP any compliant forms.

Yes! The March 18 is a deadline for you to safeguard forms from the Auto-Compliance Script.

We intend to process a small group starting on March 19 and will continue to process others over the following week. Please be prepared by March 18.

No. You can continue to work on your forms after the March 18 compliance deadline.

Protections are in place to ensure those ACH dedicated forms are untouched with this process.

Ensure the appropriate merchant account has been selected. If not, update it immediately.
Review donation forms to ensure that the layout is as you intend and fix any custom data elements that may have been displaced.

Classic Blackbaud Checkout using the S1300 Tag was updated to use PCI-compliant tokens instead of credit card data, so your implementation can continue to work as long as you have configured your merchant account and completed the steps described in Checkout using the S1300 Tag.
Setup

Note: The new requirements only apply to forms that are published and actively accepting transactions. Start with forms that will be active from March to June 2025. This may decrease the forms you need to address.
Reviewing and updating your forms is a big job, but it doesn't have to be overwhelming. Use the project guide below start making a plan that works for you. We recommend the following approach.
-
Identify your needs. Make a list or calendar of campaigns, events, and communications you know you are expecting from March through June 2025. What donation forms do you need for those? These are the priority.
-
Identify forms to prioritize those that require action. Use the Donations by Form report to identify forms that apply to the March through June 2025 priorities. Unpublish or archive unneeded forms.
Tip: New eLearning, Auditing Active Donation Forms, is now available.
-
If you do not have Blackbaud Merchant Services and Blackbaud Payment Services accounts, create them. See Get Started with Blackbaud Merchant Services.
Tip: New eLearning, Understanding Secure Payment Processing / Blackbaud Luminate Online, is now available.
-
Complete the steps in Update your Checkout Experience for Donation Forms.
Tip: Add a new checkout data element without removing the existing Payment Type data element. When both data elements are present and the selected merchant account supports the new checkout, only the Checkout element is used. Having the Payment Type data element present allows you to roll back changes more easily if you decide you are not ready for the switch.
-
If you have API forms, update your corresponding shadow form and adjust your code to call the new checkout API methods. See the Checkout overview in the API docs for more details.

Each donation form belongs to a campaign, and each campaign is associated with a Luminate Online merchant account.
To change the merchant account on a donation form:
-
Select Fundraising and Donation Management.
-
Edit a campaign on the list.
-
Open Choose Financial Options and select a merchant account
-
Save your changes.
TeamRaisers are associated with a donation form, and the donation form is associated with a donation campaign. That donation campaign is assigned a merchant account. To change the merchant account on a TeamRaiser, change the merchant account on the associated donation campaign.
To change the donation form associated with a TeamRaiser:
-
Select Fundraising and TeamRaiser.
-
Edit a TeamRaiser on the list.
-
Open Select Fundraising Options and select a Donation Form.
-
Save your changes.

-
Select Fundraising, Donation Management, and All Donation Forms.
-
Edit a donation form on the list.
-
Select Design Donor Screens and Edit the Donation Form screen.
-
Under Select data elements to include in this form, select Checkout modal or Checkout embedded and Add. Do not remove the Payment Type element.
-
Position the data element where you want it in the form by selecting the element name and using the Order arrows.
-
Select Save Order and Edit Selected.
-
Select your checkout configurations and Preview or Save your changes. Below is an example of the options in the modal element.

If you have a non-custom secure domain, either secure2.convio.net
, secure3.convio.net
or secure8.convio.net
, you do not need to take action. Once your forms are set up with checkout, Apple Pay automatically displays as an option on compatible Apple devices.
If you have a custom secure domain, complete the one-time verification process. You must complete this process even if you previously set up Apple Pay to work in legacy Blackbaud Checkout, as the verification file contents have changed.
-
Using FTP access, place the Apple Pay verification file (new checkout version) at the following path on your website:
[DOMAIN]/.well-known/apple-developer-merchantid-domain-association
.Note: If this is your first time setting up Apple Pay, create the
.well-known
folder at the root level of your site. Folders that begin with a period (.
) are hidden by default — if you don't see yours, check your FTP application's instructions for steps to view hidden folders. -
From the Blackbaud Merchant Services Web Portal, under Settings, Payment Domains, add and verify your domain.
-
Repeat for each domain and subdomain where Apple Pay should appear.
Note: Apple Pay displays 24 to 48 hours after a form processes its first payment, so if this is a new form, complete a credit card payment through the form, then wait 24 to 48 hours to check your form from a compatible Apple device to confirm that Apple Pay appears during checkout.
For more information, see Payment Domains.

To accept PayPal and Venmo through your forms, connect your PayPal Business and Blackbaud Merchant Services accounts in the Blackbaud Merchant Services Portal. See Get Started with PayPal in the Blackbaud Merchant Services Help.
Note: PayPal is not yet available for recurring payments.

Yes, all live donation forms need to be updated by February 2025. First, prioritize your live donation forms, then update lower priority forms.

No. When a campaign is updated to use the new checkout, all forms associated with that campaign must also use the new checkout. Add either the Checkout modal or Checkout embedded element to the form.

First, be aware that the embedded version that sits inline with your Luminate Online form is only available when the merchant account uses Blackbaud Merchant Services. If you do not use Blackbaud Merchant Services, you must use the modal version.
Overall, consider whether you want to offer a checkout experience to primarily capture gifts quickly. If you are wanting to offer fields for honor/memorial, or to capture full constituent information, you may want to use the embedded version which sits inline on your form amid the standard or usual fields that you want to offer.

The new checkout automatically supports all credit cards, so you no longer need to select specific cards during configuration of your Luminate Online merchant account. We have removed these options from the configuration options.
Payment processing

Yes, you can use your existing Blackbaud Merchant Services Account. You will, however, need to create a new payment configuration (merchant account) in Luminate Online.
If you are new to Blackbaud Merchant Services, see our guidance for setting up Payment Capabilities.

No. Payment Card Industry requirements do not apply to ACH.
If you currently process ACH transactions with a direct payment gateway such as iATS or Payflow Pro, you can continue to do so. However, all credit and debit card transactions will require the new checkout via Blackbaud Merchant Services with native direct debit support.
You cannot have the new checkout experience and your legacy checkout experience on the same form. Going forward any form that allows credit and debit card payments will not support third party gateways such as iATS or PayflowPro.
Tip: We recommend that you migrate direct debit recurring gifts from your current direct payment gateway to Blackbaud Merchant Services to consolidate payment processing vendors, reconciliation, reporting, and admin processes. Processing all transactions through Blackbaud Merchant Services allows you to take advantage of all new features and capabilities as an end-to-end solution for credit and debit card, direct debit, and digital wallet transactions.
Warning: If you do not migrate your existing direct debit recurring gifts to Blackbaud Merchant Services, you will have to maintain two workflows. The first for all existing direct debits to be run with your direct connect payment gateway, and the second for all new direct debit transactions that will be processed with your Blackbaud Merchant Services account.

No. Changing forms to inactive/archived does not impact your scheduled recurring transaction processing.
Once a form processes a payment, the donation data is converted to a token within Luminate Online and used in an automated workflow process for charging and processing recurring gifts. The gift data is not tied directly to the form it was collected from.

Yes, they will continue to work if they were processed on Blackbaud Merchant Services.

Yes, you can choose payment methods to offer on your donation form, including digital wallets, credit card, and direct debit options.
PayPal requires specific action, so unless you complete the configuration, it will not display. To accept PayPal and Venmo through your forms, connect your PayPal Business and Blackbaud Merchant Services accounts in the Blackbaud Merchant Services Portal. See Get Started with PayPal in the Blackbaud Merchant Services Help.
Note: PayPal is not yet available for recurring payments.

-
Credit cards support both single and recurring payments.
-
Direct debit supports both single and recurring payments.
-
Apple Pay and Google Pay support both single and recurring payments.
-
PayPal currently supports single transactions. Support for recurring PayPal transactions is coming soon.
-
Venmo currently supports only USD and single transaction processing.

Coming in 2025 to Luminate Online forms, Complete Cover/Blackbaud pays is when Blackbaud covers the fees for the form and donors have the option of giving an additional amount to Blackbaud to help support organization's that use Blackbaud Merchant Services for processing.
With this option, even if a donor decides not to contribute extra, processing is always free to your organization. See the Knowledgebase article, What is the difference between Complete Cover/Blackbaud pays, Donor Cover, and My organization pays?

Yes, coming in 2025 to both the modal and embedded versions of the new checkout will offer Donor Cover as an option on your form so that your supporters can opt to cover processing fees.
Donor cover is an optional selection in Blackbaud Checkout where supporters can agree to cover your organization’s fixed, online transaction fee for their one-time donation. Offering this option allows your organization to retain more revenue for your mission.
When the donor selects the option, Blackbaud Merchant Services automatically calculates the fee and adds it to the gift amount total.

Coming in 2025, Donor Cover and Complete Cover will provide a fee coverage option for your forms.
Donor Cover lets donors cover the processing fee so 100% of their donation goes directly to you. We’ll automatically calculate the fee for each transaction and add it to the gift amount. The full amount is tax-deductible.
Complete Cover provides fee coverage by Blackbaud for each transaction up to $3,000. In exchange, we ask the supporter to give toward Blackbaud’s service, which eliminates your processing fee. You're responsible for paying the fee for each transaction equal to or greater than $3,000 through a Complete Cover-enabled form.

It depends on whether the transaction is online or offline.
-
If the decline is for an online transaction, the decline is recorded in Blackbaud Merchant Services but not in Luminate Online.
-
If the decline is for an offline transaction, the decline is recorded in both Luminate Online and Blackbaud Merchant Services.
Why is this? Sometimes, unsuccessful online gifts are not recorded because no payment token gets created. For example, when a payment fails for an online transaction using the new checkout, an error message informs the donor and suggests they try again. If the payment fails again, no further action is taken. In this scenario, the decline is not recorded, because the authorization failed before any capture occurred, so no payment tokens were created.
For offline recurring gifts, if a payment declines, the decline is recorded in Luminate Online, and autoresponders are sent to the donor to inform them of the failed transaction. Autoresponders typically include a link to the Gift Service Center, where the donor can update their card information, if needed. Luminate Online also has retry settings to attempt the declined recurring gift at a later date and time.
You can review all captured declined transactions by logging into your Blackbaud Merchant Services portal and running a transaction list report for declined transactions.

With the implementation of PCI-compliant checkout, changes have occurred for how billing address information is sent to and stored within Blackbaud Merchant Services.
Blackbaud Merchant Services only stores the data required for the success of a donation.
-
For credit card payments, only the card name, email address, and zip code is stored.
-
For digital wallets, only the information selected to be shared by the donor is stored.
Currently, the billing address is not sent or stored in Blackbaud Merchant Services, because it is not necessary for the success of the payment.
To reconcile donation data between Luminate Online and Blackbaud Merchant Services, use the Transaction ID and parameters such as, date, time, last 4 numbers of the card, card expiration date, name, amount, and zip code.
Digital Wallets

Yes! Checkout supports Apple Pay and Google Pay for single and recurring transactions. Initially, checkout will support single transactions with PayPal, with support for recurring PayPal transactions coming soon. Currently, Venmo only supports USD and single transaction processing.
Tip: To accept PayPal and Venmo transactions, link your PayPal business account to your Blackbaud Merchant Services account. See How to set up PayPal (and Venmo) with Blackbaud Merchant Services.

Some payment methods, such as Apple Pay or Google Pay, require specific browsers. See the Supported browsers section in Digital Wallets.

Most refunds function as they did previously, but with the new checkout feature, Luminate Online now offers Blackbaud Merchant Services integration with PayPal and Venmo. This means you can process PayPal and Venmo refunds directly within the Luminate Online admin interface, just like other digital wallets, ensuring the request is handled and data is synchronized.
It's best to process all refunds within Luminate Online, as it fully manages the refund request and ensures data synchronization, keeping totals accurate whether you're viewing data in Luminate Online or an external service like Apple Pay or Blackbaud Merchant Services.
If you issue a refund directly through Blackbaud Merchant Services or PayPal, the refund will not sync back to Luminate Online, leading to discrepancies in total amounts.

Supporters can pay with Apple Pay for one-time and recurring gifts when using a compatible Apple device with the latest version of iOS or iPadOS support, watchOS, or macOS supported versions.

Currently, PayPal and Venmo are not available for recurring gifts. If you use a merchant account with a PayPal and Venmo configuration on a form that has recurring payments enabled, the PayPal and Venmo payment options are hidden.
Note: TeamRaiser Delayed Self Pledges process as recurring gifts. Therefore, PayPal and Venmo are hidden on TeamRaiser forms allowing Delayed Self Pledge.
Support for PayPal recurring gifts is coming soon.

Apple Pay and Google Pay are only included when Digital Wallets are enabled. Apple Pay and Google Pay process at the same rate as credit cards in Blackbaud Merchant Services.

Support for PayPal and Venmo in eCommerce, Ticketed Events, Personal Fundraising, and Donations Classic is coming in the March 25.2 release.
General

Our 2024 and 25.1 releases provide new checkout support for donation forms, online and offline TeamRaiser registration and gifts using checkout modal, Participant Centers, eCommerce, Personal Fundraising, Ticketed Events, Event Management Center, Donations Classic, and Embed a Donate Button.
In our upcoming 2025 releases, we will provide checkout support for the Gift Service Center and embedded (inline) checkout for TeamRaiser registrations.

Existing forms will continue to work with existing configurations up to the compliance deadline date in March 2025.

No. Changing forms to inactive/archived does not impact your scheduled recurring transaction processing.
Once a form processes a payment, the donation data is changed to a token within Luminate Online and used in an automated workflow process for charging and processing recurring gifts. The gift data is not tied directly to the form it was collected from.

Archiving a page or a donation form means moving it to a separate section for storage or reference purposes, making it no longer active or visible on the main list. On the other hand, unpublished pages or donation forms are still in the system but are not currently viewable or accessible to the public.
When a page or donation form is archived, it is essentially being stored away, while unpublished items are simply not displayed but still exist within the system.

First, change the merchant account on your campaign to use your previous merchant account. Go to Fundraising, Online Giving, and select Edit for the campaign. Select Choose Financial Options, then choose your previous merchant account.
Next, take action on your form:
-
If this is a copy of a previous form, unpublish the copy and republish your original form. See Publish a Donation Form.
-
If this is the original form (not a copy), and the Payment Type data element is included (in addition to the Checkout modal element), your form will process payments as it did before, because the checkout element will be ignored now that the campaign merchant account is reset.
-
If this is the original form (not a copy), and the Payment Type data element is not included, add the Payment Type element back to your form. See Payment Type Data Element.

No. Currently, reCAPTCHA is required and provided by default for online forms that use the new checkout to collect payments.

No, the modal is a nested iFrame window that is not impacted by browser pop-up blockers.

Yes, you are now able to add all of the standard field selections in the same donation form that uses checkout.

This experience remains as it is today. The only thing that will change is the payment section.

The original (Legacy) Blackbaud Checkout using the S1300 Tag remains without change and will continue to process transactions. We've updated the original version of checkout to be fully compliant with PCI v4 requirements.
Transactions through Legacy Blackbaud Checkout continue as XCheckout and Secure Checkout payment types.

Yes, when your site is configured for MultiLocale and set to use French-Canadian language, supporters will see checkout screens using French-Canadian language.

If you have a development site on the Cluster 8 environment, you can become familiar with working on some of the setup steps, but the checkout feature will not load when previewing or testing the form. This is due to a security measure in the environment.
To test your forms on your production site, you can make a copy of your campaign and forms, then set up checkout on those forms. Publish the copied forms when you are ready, and unpublish the original forms.

Yes, this functionality will be available.

If you need to create a basic donation form so that you can continue taking payments following the compliance deadline and auto-migration script, see the Knowledgebase article, Donation form is not working after switching to checkout. How can I create a simple form and page wrapper to use?
Customization

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.
-
Select Fundraising, Donation Management, and All Donation Forms.
-
Edit a donation form on the list.
-
Select Design Donor Screens and Edit the Donation Form screen.
-
On the left, under Arrange the order of the selected data elements, select either Checkout modal or Checkout embedded.
-
Select Save Order and Edit Selected.
-
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.
TeamRaiser

By March 2025, your TeamRaiser event must use a donation form that is associated with a campaign configured with the new checkout.
-
Go to Fundraising, TeamRaiser and Edit.
-
On the left, select Edit Fundraising Options.
-
Choose a donation form. The form must be associated with a campaign that is set up to use checkout.
-
Save the update.
Note: Support for inline checkout for TeamRaiser registrations is coming in a future release.
For more help, see Fundraising Options for TeamRaiser Events.
API

If you currently use APIs for your forms, then by March 2025, you must update certain methods to use new APIs that pass tokens to meet PCI v4 standards. Forms that use the APIs of donate
, addGift
, and offlineOrganizationGift
will work until March 2025, but you should make plans to identify your active forms and understand the updates you must make.
The new methods below use transaction tokens to handle payment information, and are only compatible with transactions in the new checkout to meet PCI v4 requirements for credit and debit card transactions
NOTICE: Until March 2025, the previous and new APIs listed below will continue to work concurrently. After March 2025, the previous methods will be deprecated.
NEW method | PREVIOUS method |
---|---|
donateCheckout - See donateCheckout. |
donate
|
offlineOrganizationGiftCheckout - See offlineOrganizationGiftCheckout. |
offlineOrganizationGift
|
See the Luminate Online API Changelog for full details.
The following new methods verify your form:
-
validateDonateCheckout
validates whether the payload passing indonateCheckout
is valid or not. -
validateProcessRegistration
validates whether the payload passing inprocessRegistration
is valid or not. -
validateAddGiftCheckout
validates whether the payload passing inAddGiftCheckout
is valid or not. -
validateOfflineOrganizationGiftCheckout
validates whether the payload passing inOfflineOrganizationGiftCheckout
is valid or not.
Updated API methods
-
addGiftCheckout is supported for all payment types. If you use
addGift
for offline payments, theaddGift
API will continue to operate along with our newaddGiftCheckout
API until March, when only theaddGiftCheckout
API method will remain. -
Both
processRegistration
andrefundTransaction
were not replaced so as to minimize impact. However, changes were made to their logic and behavior. The new behavior reviews whether a transaction token is passed in the payload instead of card credentials. Until March 2025, if the transaction token is not passed in the payload, then these APIs revert to reviewing the card credentials passed within the payload and behave as the APIs do today. After March 2025, the APIs will only operate using transaction token data. The APIs were also updated to handle any transaction type supported in Luminate Online, including checkout transactions. In a future release,ProcessRegistration
will handle PayPal payment methods (and other payment methods), soprocessRegistrationPaypal
will no longer be needed. -
getTeamRaiserConfig
no longer returns a transaction token or payment information.
See our Overview of Checkout API for information on the Luminate API updates.
See our Integration Guide for steps to connect Luminate Online forms with Blackbaud Merchant Services.
Note: startDonation
is unchanged.
Reports

Run the Donations by Form report to identify active forms and review checkout readiness. The report includes the following information:
-
Checkout Ready column: Indicates if a form is configured with a new checkout payment capability.
-
Checkout Element column: Shows if a form includes the MODAL or EMBEDDED checkout data element.
-
Transaction data:
-
Shows the number (count) of transactions processed through a form.
-
Shows the total monetary amount raised through a form.
-
Identifies active API forms based on transaction processing.
-
Tip: If you have API forms, you need to update your corresponding shadow form and adjust your code to call the new checkout API methods. See the API documentation.
Note: Highlighted columns below in yellow include transactional data from August 2024 onward. Columns highlighted in green include modified or new forms from the 24.4 release onward.
See the Donations by Form Report help documentation.

Transactions processed through checkout show a Tender Type Name as "XCheckout."
Tender Instance Name, also called Payment Method, displays the specific payment type selected, such as Apple (for Apple Pay), Google (for Google Pay), Venmo, etc.

Transactions in the new checkout appear in the Blackbaud Merchant Services Web portal as they previously did with the exception of the reference number.
When a transaction flows through the new checkout, the reference number will be prefaced with either a ch, pi, or py.
All other data displays as it did previously.

Refunds appear in the Blackbaud Merchant Services Web portal with a source of Refund, and a reference number that is prefixed with re.

Direct Debit charges appear in the Blackbaud Merchant Services Web portal with a Source of Direct debit, and a Reference number that is a series of alphanumeric characters with no prefix.
Troubleshooting

This error can occur when the PayPal account is restricted. For steps to resolve the restriction and remove the error, see the Knowledgebase article, PayPal or Venmo error: Cant process payment. Try again or contact us for assistance. - when using checkout.

On an embedded checkout form, a spinning wheel can occur when custom JQuery code in the Page Wrapper or the donation form's HTML Caption data element conflicts with JQuery code used by Luminate Online.
An update to handle custom JQuery code is coming in an upcoming release, but you can take steps now to resolve the issue. In your Page Wrapper or HTML Caption element, you can either:
-
Remove the conflicting version of JQuery.
--or--
-
Update your code to include
jQuery.noConflict()
before the custom JQuery code, so that it doesn't conflict with the existing jQuery version in Luminate Online.
To resolve this issue in the Page Wrapper: Review the configuration of your Page Wrapper for any custom JQuery code that might cause conflict. Make a Copy, then either remove the JQuery code or include jQuery.noConflict()
. For editing guidance, see, Edit an existing version of a wrapper.
To resolve this issue in the HTML Caption element on your form:
-
Go to Fundraising, Donation Management.
-
Select Manage from the Actions column for the campaign.
-
Select Edit from the Actions column of the donation form.
-
On the left, select Design Donor Screens.
-
In the list of Donor Screens, select Edit from the Actions of the donation form.
-
In the Form Designer right pane, select the HTML Caption element and click Save Order and Edit Selected.
-
In the lower portion of the Form Designer, select the Edit Data Element tab.
-
Locate the JQuery code that was added to your form. For example, in the image below, JQuery version 1.7.2 was added.
-
Remove any custom JQuery code or include
jQuery.noConflict()
. -
Click Finish.
-
Validate the JQuery version in the browser console with the command,
$.fn.jquery
. Until the March 18 25.2 release, the JQuery version should return as 3.6.0.

Checkout-enabled donation forms with custom Donor Cover code may face an issue where transactions are marked as not processed if the fee cover amount isn't added to the user_donation_amt
field.
To ensure that final amount, including the fee cover, is correctly reflected to the donor and processed fully, make sure the custom code writes the final amount to the user_donation_amt
field. This code might be located in your Page Wrapper or donation form.
To resolve this issue, you can either:
-
Update the custom Donor Cover code to ensure the final amount is processed
--or--
-
Remove the custom Donor Cover code
To update the code, find the Donor Cover code in your Page Wrapper or donation form. For example, if you have:
$('.donation-level-user-entered input[type="text"]').val(donateAmt);
Update the code to
$('#user_donation_amt').val(donateAmt);

This message can occur when an existing merchant account has a gateway set for the S1300-Tag version of Legacy Blackbaud Checkout, whether or not the feature was used. The message displays when trying to update an existing campaign's merchant account.
Resolving the message best depends on whether you want to use the S1300-Tag Legacy Blackbaud Checkout version.
If you do not want to use the S1300-Tag Legacy Blackbaud Checkout, and you want to update your existing campaign, disconnect Legacy Blackbaud Checkout from the original merchant account using the following steps:
Note: The following steps change the behavior of all donation campaigns that use the merchant account.
-
Go to Setup, then Payment Capabilities.
-
In Merchant Account, select Edit next to the existing merchant account.
-
In the Legacy options section, change the Legacy Blackbaud Checkout Account selection to No Gateway Selected.
-
Select Save.
-
Return to edit your campaign, select your new checkout merchant account, and Save.
However, if you do not yet want to disable the S1300-Tag version of Legacy Blackbaud Checkout from use everywhere, make a transition merchant account to allow for migration of certain donation campaigns to use the new checkout, while other campaigns can continue to use the Legacy Blackbaud Checkout. Follow these steps for campaigns that will use the new checkout:
-
Make a transition merchant account:
-
Go to Setup, then Payment Capabilities.
-
In Merchant Account, select Create Account.
-
Configure all of the options in the Legacy options section except the field for Legacy Blackbaud Checkout Account.
-
Select Save.
-
-
Update the existing campaign to this new transition merchant account to allow migration.
-
Go to Fundraising, then Online Giving.
-
In the Campaigns list, select Edit for the appropriate campaign.
-
Select Choose Financial Options and select the new transition merchant account.
-
Save your change.
-
-
Update the same campaign to now use the new checkout gateway.
-
Go to Fundraising, then Online Giving.
-
In the Campaigns list, select Edit for the appropriate campaign.
-
Select Choose Financial Options and select the merchant account appended with "Checkout" from the list.
-
Save your change.
-

Sometimes, messages or errors coming from Stripe elements appear in the console of Mozilla Firefox. The errors do not prevent payment processing and are related to cross-site tracking.

Sometimes, the donateCheckout API method can result in the error, "There was a problem encountered while processing your donation," when the payment zone is not passed as an argument in the method. When this occurs, transactions will not process and the call gives a 404 error that the resource is not found.
To resolve this, ensure that you first execute either getDonationFormInfo or getTeamraiserConfig before calling donateCheckout.

Sometimes this error occurs when custom JavaScript in a reusable PageBuilder page conflicts with code in Luminate Online.
To resolve this, review your reusable PageBuilder pages for custom JavaScript and remove the custom code.
Don't see your question here?
Please use the feedback form below to submit your question.