Donation processing

Understand the lifecycle of a payment transaction in NationBuilder — what happens after a donor enters their card and hits "submit"?

Updated over a week ago

Table of Contents

Payment processor

A 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. If you are using a 3rd-party processor, you may need a merchant account. A merchant account is a type of bank account that accepts money via credit card. 

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, they are 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

If you are using NationBuilder’s integrated payment processing, you can refund transactions from within your control panel.

To refund a donation go to the donor's personal profile and click Finances > Donations and locate the donation you want to refund. 

1. Hover over and click Edit next to the donation.

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

When the refund is successful, a 'canceled at' date is added to the payment transaction as the date it was refunded.

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

Refunds with third-party processors

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

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 [email protected] if you wish to resolve this conflict.

Refund problems

  • You do not see a "Refund donation" button in the settings section of a donation of a payment processor where this option should be available.

  • A donor reports that they have not received a refund you sent (after 5-10 business days).

Making partial refunds

From your control panel, it is only possible to refund a transaction in its whole amount. Partial refunds made from a third-party payment processor will not be reflected in your control panel.

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 recurring donor's credit card will be charged on the same day every month. You can explicitly call the date with the Liquid variable: 

{{ donation.succeeded_at | date_to_string }}

You can change how the date is displayed by what editing the filter that appears after the trunk (i.e. after the " |" above). A full list of date-based Liquid filters is available.

For example, on a donation page accepting one-time payments and installment payments, you could use the following if Liquid logic markup 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 }}.

Related HOWTOs


Did this answer your question?