Accepting Donations In Multiple Currencies

ActionKit supports collecting donations in multiple currencies through Braintree and PayPal. Read more about our paypal integration.

Our foreign currency system was designed primarily for country-, or possibly currency-, specific use. The set up is a like supporting another language: donation campaigns will generally need distinct pages and mailings per currency, and your reporting may work slightly differently as well.

We have added a currency switcher, which allows you to accept donations in multiple currencies on one page through Braintree. Read more about this below.

Getting Merchant Accounts From Braintree

You need to get in touch with Braintree at accounts@braintreepayments.com to fill out the necessary paperwork to get merchant account IDs for each currency in which you want to accept donations. Once you have the account, send us your new merchant IDs, and which currencies they correspond to, through the ticket system.

To accept recurring gifts in other currencies, you also need to add recurring plans for each one: in the Braintree admin, click Recurring billing -> Plans in the left sidebar, then click New. For the ID, use the three-letter currency code (for instance, EUR for euros). Enter any name and price you want, choose a billing cycle of one month, and click Create.

Braintree support has more details on how it works on their end.

Setting Up Pages

Foreign-currency pages are mostly like any other. In the Payment account dropdown, you'll now see an account name with your new currency code appended, like "Braintree EUR"; pick that. To use a suggested ask formula, you must create a formula specific to the page's currency. The same is true for products; you must create a version of the product with the price in the page's currency.

For easier internal reporting, you may want to group a set of related donate pages into one multilingual campaign. In this case, the "multilingual" campaign just allows the set of pages to be treated as one unit in the Reports tab (but not thermometers), and can be useful even if the pages involved aren't actually in multiple languages.

You can also accept donations in other currencies through PayPal. With PayPal, the user can donate in any currency that PayPal accepts, regardless of which account you choose as the Payment account. Read about Paypal's international donation support.

Currency Switcher (formerly known as Account Switcher)

You can include a link for each currency for which you have a Braintree account set up, by checking the Display Currency Switcher box on the Action basics screen. Users can select their desired currency and their donation will go through the corresponding account.

If you include the switcher on a page with a product, product orders may fail because products are associated with only one currency.

If you check the box, but don't see the links on your donation page, you may be using an old templateset that doesn't support this functionality.

Templateset Changes

Templatesets created before the multicurrency feature was rolled out will need updates.

  • Orders and related objects now have an 'amt' property you can use in templates automatically write out a currency prefix: '{{ order.amt }}' can replace the old '${{ order.total }}'.
  • Raw numeric amounts can be prefixed by '{{ page.currency_sym }}'.
  • For action notifications, you can send staff a rough conversion of the order amount into dollars using '{{ order.total_converted }}'.

The Original templates already have these changes, and the default donate.html might be useful as sample code. Original's changes are just enough to make sure we unambiguously show currency units where we need to. If you want, you can change some other things to match your target countries' conventions for currency display:

  • Currency symbol/code placement: Some countries put the currency after the amount (e.g., France). To do that, your templates can use '{{ order.total }} {{ page.currency_sym }}' instead of '{{ order.amt }}'.
  • Decimal/thousands separators: ActionKit's 'commify' filter lets you specify separators. For the amount 1000.00, {{ amount|commify }} outputs "1,000.00" (for the U.S.), {{ amount|commify:", " }} outputs "1 000,00" (for France), and {{ amount|commify:",." }} outputs "1.000,00" (for Germany).

PayPal has separate account set up and templateset change requirements.

Sending Mailings

For most mailings requesting donations in different currencies, you'll need to create a separate mailing per currency. Each mailing should link to, and have set as its Landing Page, a page using the correct currency for the countries it's targeted at.

All the one-time Donation snippets work exclusively in the landing page's currency. For example, if the page solicits Euros, donations.highest_previous will pull the user's highest Euro donation and ignore any made in dollars or yen. Also, the mailing will use the Suggested Ask Rules from that page.

Recurring Donation snippets include both one-currency snippets (which will use the currency from the landing page) and multi-currency snippets, which will use the currency of the relevant recurring donation profile for each user.

After you send, the individual mailing report and the performance-by-mailing page will show both the total amount given in the currency of the landing page and an approximate conversion into US dollars for your convenience.

Uploads

ActionKit's upload system supports a donation_currency column with a three-letter ISO code. You can import donations in currencies other than the ones you have payment accounts for, as long as the three-letter currency code is one known to ActionKit. Conversions into approximate US dollars will be done using ActionKit's exchange rate estimate at upload time, regardless of the actual date of the donation.

Reporting

Multiple currencies make reporting trickier because fields like total and price no longer always reflect consistent units. We handle that two ways: giving specific units where that's straightforward to do, and using amounts converted to US dollars elsewhere. Specifically:

  • In admin UI where amounts are usually in a single currency, we report numbers in that currency, plus a rough conversion to US dollars. For instance, the user's action history lists donations this way.
  • In SQL reports and some other places, we report totals using rough conversions to US dollars. For instance,the "Your Progress" report gives total donations using the actual amount of US dollar donations and the estimated conversion for other donations.

Converted numbers are in '_converted' columns, like core_order.total_converted and core_order_detail.amount_converted. Currency codes are in columns named 'currency'.

Remember that our conversions into US dollars are just for your convenience, and you shouldn't rely on their accuracy for a few reasons. First, we may not be using the same rates or converting at the same time as your payment processor: we use the free feed from openexchangerates.org, updated at most hourly, and do the conversion at donation time. Second, there could be errors in our conversion or exchange rate updating: bugs happen, and these conversions are one of the more specialized and rarely-used parts of ActionKit. So, while we want conversions to be useful and would like to hear about any bugs you run into, you should not assume the converted numbers you see are money in the bank.