Donation processing

How a donation is processed

To process a donation, you'll need to connect a payment processor. A payment processor allows you to accept donations online and process invoice payments by charging the donor's credit card and sending the money to your bank account. 

NationBuilder sends the donor's billing information and credit card number to the payment processor's API. Every aspect of this communication is done using secure HTTP. From the donor entering her credit card number to NationBuilder passing the information to your payment processor to NationBuilder receiving confirmation that the transaction was successful, all of the transmissions are secure.

The payment processor stores the donor's contact information, credit card number, expiration date, and security code. The processor then passes this information along to the donor's credit card company (Visa, MasterCard, etc.) to check whether the data is valid and approve the transaction. Once the information is confirmed, the processor charges the credit card. The processor then tells NationBuilder that the transaction was successful. 

Sometimes, a problem occurs in processing the transaction and the processor responds with an error message. Communication with a payment processor happens in milliseconds. So if the donor enters his credit card number incorrectly, or makes another data entry mistake, it is possible for him to see an error message on your donation page related to processing the donation. Simultaneously, this information is recorded in your control panel.  

Payment processor

payment processor handles charging a person's credit card and sending the money to your bank account. 

You'll need a bank account connected to a payment processor to take donations online or process invoice payments. Depending on the processor, you may need a merchant account. A merchant account is a type of bank account that accepts money via credit card. 

Related resources:

How to connect a payment processor, includes a list of payment processors integrated with NationBuilder

Payment transactions

A payment transaction is a common term used in various financial systems. A payment transaction represents each communication made between NationBuilder and a payment processor. When a donor clicks the "Donate now" button on your website, she is authorizing NationBuilder to submit the credit card information to a third party, the payment processor. 

Prior to submitting the request, a payment transaction object is created in your nation's database to log the communication. NationBuilder updates the payment transaction when the payment processor responds. The response contains a response code, message, authorization code, transaction ID, and other data.

Payment transactions are displayed on the dashboard of a donation. Each donation lives within the Finances section of a profile. 


A successful payment transaction will look something like this:


Here are examples of failed transactions:




Each of the above attempted transactions are displayed on different donations. 

A donation can have zero or more payment transactions associated to it. Each payment transaction is displayed in the dashboard of a donation record.

Examples of how donations and payment transactions interact:

  • When you log receipt of a donation made via cash or check, no payment transaction is created.
  • If someone tries to donate on your website and she types in her card number incorrectly, a failed payment transaction will be added to the donation in your database. A message will also display on the donation page and the website visitor can re-enter her information. Re-entering her credit card information will trigger the creation of a new donation. The second payment transaction will be connected to this second donation.
  • Another possibility in the above situation: Someone tries to donate on your website and she types in her card number incorrectly. The failed payment transaction is added to the donation and a message displays on the donation page. The potential donor ignores the message. A control panel user calls the donor to ask her to complete her donation over the phone. The control panel user then edits the donation, enters the credit card information correctly and submit the donation. A second, successful payment transaction is added to the original donation.
  • Editing a donation within the control panel is the only way a failed donation will have more than one payment transaction.
  • Installment payments and monthly donations will also create multiple payment transactions on a donation record.

Transaction ID or key

A transaction ID, also known as a transaction key, is a unique identifier generated by a financial system to reference a successful payment for a given amount. It is used to reference data between various systems. This ID is not generated by NationBuilder - it is created by the payment processor for a successful payment to identify financial data stored in NationBuilder. 

You can think of this ID as a foreign key or a reference key between two systems. For most payment processors, the transaction ID is displayed in the donation dashboard within a payment transaction. Here is an example:


Only successful payment transactions have associated transaction IDs. A transaction ID can be used to search payment transactions in the payment processor portal. This ID is required to refund a donation.

How to refund a donation

You can refund transactions from your control panel if you are using, Paypal Payflow Pro, SagePay, eWay, or Stripe.

1. To refund a donation go to the donor's personal profile. 

2. Go to Finances > Donations and locate the donation you want to refund. 

Finances > donations

3. Click on Edit icon next to the donation.

4. Scroll to the bottom of the page and click on the "Refund donation" button.

Refund donation

When you click the button, NationBuilder asks the processor to refund the full amount of the transaction. The transaction ID confirms which transaction needs to be refunded. When the refund is successful, a 'canceled at' date is added to the payment transaction. The 'canceled_at' field of a donation is the date it was refunded.

Refunds outside of the control panel

Sometimes refunds are not possible from your control panel. You cannot process a refund from the control panel if:

1. The donation was processed using Democracy Engine or PayPal Express Checkout.

2. You want to provide a partial refund rather than a complete refund.

3. A transaction ID is not associated with the donation. A successful donation processed by, Paypal Payflow Pro, SagePay, eWay, or Stripe should always have a transaction ID. If the transaction ID is missing, it could be the result of a connection issue between NationBuilder and your payment processor.

Contact your payment processor to refund a donation if you do not see a "Refund donation" button in the settings section of a donation. Any refund submitted directly on a payment processor will not automatically reflect in your control panel. Reach out to your community strategist or, as we can help resolve this conflict.

Making partial refunds

From your control panel, it is only possible to refund a transaction in its whole amount. You can refund transactions and provide partial refunds by logging into your payment processor's website. Each payment processor has instructions on how to do a full or partial refund. Additionally, you can contact the payment processor customer support for guidance. When you complete a refund on your payment processor's website, the record of the donation will not be updated in your control panel.  

When you delete the transaction or adjust the amount in the case of an offline contribution, you can leave a note.

Note on donations

Donation receipts

When a donation is submitted on your website, two receipts are created: 

  1. An email receipt is sent immediately to the donor. 
  2. A PDF receipt is attached to the donation. You can access this receipt from Finances > Donations within a profile.

When a donation is added in the control panel, only the PDF receipt is created.

Here is an example of where to find a PDF receipt in a donor's profile:


These receipts will reflect the total amount donated on a one-time donation. 

Timing of email receipts

When a donation is made on your website, a receipt is sent via email to the donor. This email is handled like other auto-response emails created by your nation. When the donation is marked successful, the receipt is sent as a background job. First, the email is placed in a queue and then sent. Most of the time, the email is sent immediately. 

If NationBuilder is facing network issues, or if the job queue is backed up, it can take some time for the email receipt to be delivered to the donor. 

PayPal as payment processor

When using PayPal Express as your payment processor, a donor will receive two receipts via email for an initial donation: one from your nation and one from PayPal, since the payment is completed on PayPal's website. 

You can avoid emailing donors twice for a single donation by not sending an autoresponse email on donation pages attached to PayPal Express. 

Receipt for initial payment on recurring donations

If the donor chooses installment payments, the receipt will reflect the initial payment made. In the following months, your payment processor will charge the donor's credit card. No further receipts will be automatically sent to the donor. When subsequent payments occur, they will be listed in your control panel and a PDF receipt reflecting each transaction will be available.

Similarly, the receipt reflects the first month's donation when a donor begins a monthly donation. In the months that follow, donations will be reflected on the donor's credit card statements. No further receipts will be automatically sent to the donor. When subsequent payments occur, they will be listed in your control panel and a PDF receipt reflecting each transaction will be available.

Autoresponse email

The default wording of autoresponse emails can be changed. A donor's credit card will on the same day every month for a recurring donation. You can explicitly call the date with the liquid term 

{{ donation.succeeded_at | date_to_string }}

You can edit how the date is displayed by what changes what comes after the trunk ( | ) - a full list of date-based filters is available.

For example, on a donation page accepting one-time payments and installment payments, you could use the following if statement in the autoresponse:

{% if donation.is_recurring %}
Thanks for making a recurring donation.

Your card will be charged on the {{ donation.succeeded_at | %d }} day of every month.
{% else %}
Thanks for making a donation on {{ donation.succeeded_at | date_to_string }}.

If you’re unclear on how this feature works, please ask a question. If you would like to see changes to this feature, please submit a suggestion.