In addition to the main donation page instructions, these follow-up steps are required for staged donation pages. They consist of moving the payment element and billing address collection to the last step of the donation page flow. Skipping them may lead to unexpected behavior when using the payment element.
If you’re creating a new theme, you can download the bootstrap staged page conversion kit, which includes the upgraded donation page theme file with the new payment element in the correct stage of the page and the unchanged jquery files, js or scss files.
Converting a page to a staged donation page requires the following theme files: _staged-donations.scss, jquery.ui.effect-slide.min.js, jquery.ui.effect.min.js, and staged-donations.js.
Move payment element to last step in the donation submission flow
If it’s not already the case, make sure the payment method is collected on the last stage of the donation form. The donation amount is required to render the payment element and the available payment method options. Moving the payment element to the last stage in the donation page flow will ensure donors have made their donation amount selections and provided the necessary data. Once they reach the last stage to submit payment, this element will already be visible on the page. This is different from the single-page flow, where donors will see the ‘Please select or enter an amount disclaimer’ before the payment options are available.
In the current staged donation page template, the following payment method fields can be moved from around line 165 to line 190. So that the fields are within stage two. Nested within the div with data attribute data-stageID="2"
<div data-payment-disclaimer>
<p id="cc-disclaimer">Please select or enter an amount</p>
</div>
<div id="submitted-payment-method" class="row">
<div class="col-sm-12">
<p>Payment method information has been saved. <button type="button" class="btn btn-link change-submitted-payment-method">Change payment method</button></p>
</div>
</div>
<div id="cc-info" class="row">
<div class="col-sm-12">
<div class="form-group">
{% payment_field 'payments' %}
</div>
</div>
</div>
<smallid="apple-pay-notice">IfyouuseApplePay,yourconfirmationpromptmayrefertoourpaymentprocessor,"NationBuilder"</small>
Move billing address for new autocollection behavior with express payment options
This change applies to staged donation pages where billing address details are not collected on the last stage of the donation form. In the original bootstrap staged conversion kit, billing address data is collected in the second stage. These should be on the same stage as payment method collection with the payment element.
This supports the autocollection of the billing address that occurs when donors select an express payment option. The billing address fields will be hidden if an express payment option is selected, as these fields will be autocollected from the donor’s digital wallet. Billing address fields will display for payment methods where this feature isn’t available, such as credit cards and direct debit.
Based on design preferences, the billing address fields can be moved to display after the payment method selection. We recommend doing this if the payment element is moved to the bottom of the page in stage two.
Ensure the address fields are nested within the div with id address-info. This example shows the relevant fields.
<div id="address-info">
<div class="form-group">
<label for="donation_billing_address_country_code">Country</label>
{% select_field "billing_address.country_code", page.donation_v2.countries, "code",
"name",class:"form-control" %}
</div>
<div class="form-group">
<label for="donation_billing_address_address1">Billing Address</label>
{% text_field "billing_address.address1", class:"form-control" %}
{% text_field "billing_address.address2", class:"form-control mt-2 text" %}
{% text_field "billing_address.address3", class:"form-control mt-2 text
not-us-or-canada hide" %}
</div>
<div class="form-row">
<div class="form-group col-md-4">
<label for="donation_billing_address_city">City</label>
{% text_field "billing_address.city", class:"form-control" %}
</div>
<div class="form-group col-md-4 us-or-canada us-only hide">
<label for="donation_state">State</label>
{% select_field "billing_address.state", page.donation_v2.us_states, "code",
"name",class:"form-control" %}
</div>
<div class="form-group col-md-4 us-or-canada canada-only hide">
<label for="donation_billing_address_state">State</label>
{% text_field "billing_address.state", class:"form-control" %}
</div>
<div class="form-group col-md-4">
<label for="donation_billing_address_zip">Postal code</label>
{% text_field "billing_address.zip", class:"form-control" %}
</div>
</div>
</div>
Feedback for staged donation forms with three stages
For pages that use a three-stage donation submission form, we recommend applying the changes noted above where the payment method and billing address are collected on the last stage before submitting the form. This will help ensure the form can submit successfully and handle most donation error scenarios.
Any custom validation errors, styling, or other javascript applied to the custom theme will require changes to the custom theme files to align more closely with the current payment element implementation. Please feel welcome to reach out with any feedback or questions.
Testing recommendations include:
Submitting a successful donation,
Handling a card failure or digital wallet failure,
Clicking back and forth across stages on the form