All Collections
Fundraising
Mobile/Express payment options
How to update a customized theme to support express payment options
How to update a customized theme to support express payment options

Update your custom theme or customized Donation (v2) page to support express payment options

Updated over a week ago

If you have enabled express payment options for your website but the new options are not appearing on your pages, you may need to update your custom theme to support the changes.
​
The following instructions are only applicable to nations that want to retain existing customizations to their pages_donations_v2_wide.html file and intend to use this functionality on all donation pages. If this doesn't apply to you, please select a different set of instructions.

⚠️ Updating a customized theme is fairly technical. If you are not comfortable making the changes described on your own, you can to hire a certified NationBuilder partner to make these changes for you.

Table of contents

Identify your stock theme

Every custom theme is based on an original stock theme. If you're unsure of which stock theme is applicable to your website, you can right-click (or CTRL click) on your live website, and select the option to "View page source."

Once you see code on your screen, find the word "parent". The "parent" listed should be the name of the stock theme your custom theme was build off of.

Download theme files

Click on the name of the relevant stock theme below to download a ZIP file containing a pages_show_donation_v2_wide.html file and an _epo_theme.scss file.

Update your custom theme

  1. Open the _epo_theme.scss file in a text editor (not a browser), and copy and paste the code into the bottom of your current theme.scss file.

  2. Open up the new pages_show_donation_v2_wide.html file in a text editor alongside your existing pages_show_donation_v2_wide.html file to compare the changes. You can follow the Explanation of Changes table below for an explanation of each update - agnostic to theme - to help you determine where you need to make changes to your existing file.

Explanation of changes

Download this this file for an outline of a pages_show_donation_v2_wide.html file highlighting the changes described below.

1. Amount. Update the word “Amount” to remove any numbering.
​

2. Payment type selection. Add the new “Pay With” section to just below the one-time/monthly selection options.

What

Why

Result

<div>
<h3>Pay with</h3>
</div>

Renaming the credit card section to “Pay with” to make it more agnostic towards new payment types

<div id="payment-methods">

This ID allows the section to be hidden if no express payment type can be identified on the user’s device

{% if page.donation_v2.express_payment_activated? %}    
 <div id="donation-v2-payment-request">
 </div>
{% endif %}

If express payment options are enabled at both the site and page level, this allows the options to be displayed to the donor.
​
📌 Note: If you are using a theme with a dark background, you can append the following data attribute to this div to make the dynamic button use a light style in place of the dark default:
​data-epo-button-theme="light"

<div id="cc-request-button">       
 <button type="button" class="button”><i id="credit-card-icon"></i>Credit Card</button></div>

Displays the new “credit card” button for a donor to opt to pay by card instead of their available express payment method option

<div id="apple-pay-notice">    
 <small>If you use Apple Pay, your confirmation prompt may refer to our payment processor, "NationBuilder"</small>
</div>

Notifies donors using Apple Pay on a desktop device that they may be prompted to confirm their payment to "3dna CORP dba NationBuilder."

<div id="selected-payment-method>       
 <div><i id="payment-method-icon"></i><a href="#" class="change-payment-method">Change payment method</a>     
 </div>  

 <div class="span12">         
  <p>You're almost done! Submit {% if request.current_order %}payment {% else %}donation {% endif %}below.
  </p>    
 </div>
</div>

1. Allows the donor to flip back to the choice between paying by express payment option or paying by card after express payment option has been selected
​

2. Encourages donor to scroll to the bottom of the page to complete their transaction

<div id="submitted-payment-method">  
 <div>     
  <p>Payment method information has been saved. <a href="#" class="change-submitted-payment-method">Change payment method</a> 
  </p>  
 </div>
</div>

Saves the donor’s payment method in case of a page refreshed caused by an error (ex. Submission without address details) 

<div id="cc-info">     
 <div>{% payment_field 'card' %}        
  <p><a href="#" class="change-payment-method">Change payment method</a>
  </p>    
 </div>
</div>

1. Payment field allows the donor to pay by card
​
2. Allows the donor to flip back to the choice between paying by express payment option or paying by card after credit card option has been selected

3. Hide end of form. Following the credit card field, add the ID “your-info” above the start of the “Your information” section

What

Why

Result

<!-- payment_field above ^ -->

<div id="your-info">

<!-- Your Information below ˇ -->

Hides all fields after the credit card/express payment option buttons (when an express payment option is available) to minimize donor overhead in the initial selection.

📌 Note: Be sure to close this div just before the {% endform_for %} conditional at the bottom of your template

4. Donor information. When an express payment option is selected, any information that can be obtained about the donor through that payment method will be stored in those fields. Create a read-only block of the donor’s personal information to simplify the donation form, and allow the donor to expand the fields if they need to edit the data.

What

Why

Result

<div id="demographics-read-only">    
 <span id="demographics-name"></span>
  <a href="#" id="edit-demographics">Edit
  </a>
  <br />    
 <span id="demographics-email"></span>
 <br />    
 <span id="demographics-phone"></span></div>

Create a read-only block that will contain all of the donor’s information if all fields can be pulled from their selected payment method. 

<div id="demographics-info">  
 <div>    
  <div><label for="donation_email">Email</label>{% email_field "email", class:"text" %}      
  </div>  
 </div>  

 <div>    
  <div><label for="donation_first_name">First Name</label>{% text_field "first_name", class:"text" %}
  </div>    
  <div><label for="donation_last_name">Last Name</label>{% text_field "last_name", class:"text" %}
  </div>  
 </div>  

 <div>    
  <div><label for="donation_billing_address_phone_number">Phone</label>{% phone_field "billing_address.phone_number", class:"text" %}   
  </div>  
 </div>

</div>

Expand out the donor’s information if either
a) the original required information could not be collected
b) the donor clicks on “Edit” next to the block

The code comprising this section can be copied directly from your existing theme, but be sure the entire block is wrapped in the “demographics-info” ID.
​

📌 Note: We recommend moving the Phone field up into this block because that data will be displayed in the minimized, read-only block if obtained from the payment option.
​
​If the phone field is left lower on the form, it may be a confusing experience for donors who expand out the block to edit it.

5. Donor address information. Just like the personal information, address information can be compressed and expanded

What

Why

Result

<div id="address-read-only">  
 <span class="address-line">    
  <span id="address-line1">
  </span>
<a href="#" id="edit-address">Edit</a>   
 </span>  
 <span class="address-line">    
  <span id="address-line2">
  </span>    
 </span>     
 <span class="address-line">    
  <span id="address-city">
  </span>, <span id="address-state"></span>    
  <span id="address-zip">
  </span>  
 </span>   
 <span class="address-line">    
  <span id="address-country">
  </span>  
 </span>
</div>

Create a read-only block that will contain all of the donor’s address information if all fields can be pulled from their selected payment method. 

<div id="address-info">    
 <div>    
  <div><label for="donation_billing_address_country_code">Country</label>{% collection_select "billing_address.country_code", page.donation_v2.countries, "code", "name", class:"select" %}      
  </div>  
  <div>    
   <div><label for="donation_billing_address_address1">Billing Address</label>    {% text_field "billing_address.address1", class:"text" %}    {% text_field "billing_address.address2", class:"text" %}    {% text_field "billing_address.address3", class:"text not-us-or-canada hide" %}    
   </div>  
 </div>  
 <div>      
  <div><label for="donation_billing_address_city">City</label>{% text_field "billing_address.city", class:"text" %}
  </div>      
  <div class="span4 us-or-canada us-only hide">         <label for="donation_state">State</label>{% collection_select "billing_address.state", page.donation_v2.us_states, "code", "name", class:"select" %}      
  </div>      
  <div class="span4 us-or-canada canada-only hide">         <label for="donation_billing_address_state">State</label>{% text_field "billing_address.state", class:"text" %}      
  </div>       
  <div><label for="donation_billing_address_zip">Postal code</label>{% text_field "billing_address.zip", class:"text" %}      
  </div>  
 </div>
</div>

Expand out the donor’s information if either
a) the original required information could not be collected
b) the donor clicks on “Edit” next to the block


​

The code comprising this section can be copied directly from your existing theme, but be sure the entire block is wrapped in the “address-info” ID.
​
​

6. Delete old payment field. Remove the Payment Information block from the bottom of your form. If you add the {% payment_field ‘card’ %} field as instructed above, but fail to remove the original from the bottom of your form, no payment options will be displayed.

What

Why

Result

<h4>{% if request.current_order %}2{% else %}3{% endif %}. Payment information</h4>
<div>    
 <div><label>Credit Card</label>          {% payment_field 'card' %}  
 </div>
</div>

Delete this code from the bottom of your form

Related HOWTOs

Related Articles
How to upgrade your theme for Donation (v2) pages
Allow donors to cover payment processing fees
Express payment options
How to update a theme to support express payment options
How to update a page template to support express payment options
Did this answer your question?