Overview
This document details single and recurring credit or debit card transactions via the Stripe gateway.
Using the Stripe gateway, we can currently process card donations from Visa, MasterCard, American Express, JCB, Discover, and Diners Club, recurring card donations, as well as Bancontact in Belgium, iDEAL in Netherlands (Sept 2020 release) and SEPA (Euro) direct debit payments (Sept 2020 release).
Setting up Stripe
You will need to set up the Stripe gateway first by going to https://stripe.com/. To complete the set-up, they may require documentation from you for proof of identity (see this link from Stripe for more information).
We recommend that you explicitly confirm the payment methods and currencies available to you with Stripe, and if you wish to process recurring payments you will first need to have this feature enabled by Stripe.
You should also create two gateways – a live and test and use those credentials to connect the gateway to Engaging Networks (see next).
Setting up the gateway in Engaging Networks
It is recommended that you create and keep two separate gateway records in your account, one for testing and one linked to your live gateway. Donation pages should be linked to a test gateway initially, and then switched to a live gateway before launch. To create each one:
1. Go to Hello (username) > Account Settings > Gateways
2. Click ‘new payment gateway’ to create a new entry
3. The initial fields are set up as follows:
| Field | Description |
| Reference name | A unique name for the gateway. It is a good idea for the name to include the type of gateway (eg. Stripe NA), the currency, and whether it is a live or test gateway. |
| Select gateway | Select the Stripe gateway. |
| Test mode | Should be checked for a test gateway, but must be unchecked for a gateway that will accept live donations. |
4. Once complete, click Connect to connect to Stripe
If you see the error “Unable to complete Stripe connect” then temporarily change your Donation Base URL in your account settings to https://ca.engagingnetworks.app or https://us.engagingnetworks.app and try again. Once connected, you can revert the Donation Base URL back again.
5. A pop-up window appears. Log into the gateway using your Stripe credentials
6. When prompted click “Connect my Stripe account”:
7. Once connected, the gateway in Engaging Networks will save. You do not have to put any other credentials in
8. By default, Enable 3D in your gateway settings will be ticked, to enable integration with PSD2. If you wish to disable this, edit the gateway and uncheck the box
This needs to be enabled to support features such as Plaid ACH, SEPA, BACS, and digital wallets.
9. Repeat the procedure to create a live and test gateway
Required form fields
The following tagged fields need to exist in your account data structure for you to use Stripe as your gateway for donation pages. They should exist in a form block using the required format in the tables below.
Basic fields required for all payments
| Form Field | Recommend form block field type | Comments |
| Email Address | Text with Email Validator | Email address identifying the supporter record |
| Payment Type |
Select or Radio |
*This is optional if the page only accepts credit card payment types, but is required if other types like ACH are accepted on the same form. Credit Cards = CardCard |
| Donation Amount | Text, Radio with Input or Select with Input with Donation Amount validator | May be entered as a whole number or number with two decimal places. Eg. Twelve dollars may be entered as ’12’ or ‘12.00’. Should not include the currency symbol |
| First Name | Text | The cardholder’s first name. |
| Last Name | Text | The cardholder’s last name. |
| Address 1 | Text | The first address line of the cardholder |
| City | Text | The address city of the cardholder |
| Region | Text | The address region of the cardholder. For the US and Canada, this should be a 2 character code for the state/province. For other countries, it is a free text field.
Not required for the UK |
| Country | Select (you can import a list of Country Iso 2) | The country of the cardholder. This should be a 2 character ISO code. |
| ZIP/ postal code | Text | The post/postal/zip code of the cardholder |
Additional fields required for card payments
| Form Field | Recommend form block field type | Description |
| Credit Card Number | Token | Credit card number w/o spaces |
| Credit Card Expiration | Split select with no delimiter | Format must be MMYY |
|
Credit Card Verification value (CVV2 or CVC2) |
Token | The additional Card Verification Value printed on the card, used for fraud checks |
| Currency |
Offering one currency: Hidden field with default value Allowing currency choice: Select or Radio |
Format must be 3-letter ISO. Eg USD, CAD, GBP etc |
Additional fields required for recurring card payments
If you wish to allow for recurring card payments, which are managed by Engaging Networks, then you need these additional fields. Note that should a supporter make a recurring card payment, their first payment will be debited when they submit the page, and subsequent payments will go out on the scheduled day the next month.
| Form Field | Recommend form block field type | Description |
| Recurring Payment | Radio with Y and N values | Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment. |
| Recurring Frequency | Hidden field with default value | Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. |
| Recurring Day (optional) |
Hidden field | The day of the month on which the recurring payment should be taken. (1-29 are allowed)
If you do not include this field, it will assume today as the day to take the monthly donations. (e.g. submitting on the 22nd would try on the 22nd the next month) |
| Recurring End Date (optional) | Triple select with / delimiter | When this recurring payment should cease. The value must be in the format DD/MM/YYYY |
Card payment statuses – Recurring Transactions
When a recurring transaction is submitted, Stripe will record this and let Engaging Networks know whether it was successful or rejected. Until that happens, a ‘pending’ status donation will show in Engaging Networks. This log will then be quickly updated to either ‘success’ or ‘reject’ depending on what happens with the rest of page processing. You should not generally see a ‘pending’ status in exported donations.
Processing Bacs Direct Debit
You can collect Bacs Direct Debit payments associated with UK banks using the supporter’s account number and sort code to process in GBP. The payments are managed by Engaging Networks, so you can control the recurring donations from within the Lookup Supporters Recurring Donations gadget.
For information on setting up and managing Bacs Direct Debit payments, please refer to this article.
Processing SEPA Direct Debit
If you wish to provide the ability to donate via SEPA recurring bank payments (Euros) you will need to have enabled SEPA in your Stripe account and to turn on webhooks. SEPA payments work in the EU and not in the UK or US.
How does it work?
When the payment type of sepa_debit is chosen by the supporter (you can have a different label but the value must be this), an IBAN input field automatically appears after for the supporter to type into.
You do not need to place an IBAN field on the page – it will appear automatically!
SEPA Direct Debit is a “reusable, delayed” notification payment method. This means that it can take up to 14 business days to receive notification on the success or failure of a payment. The length of time that this takes will differ depending on the country and bank.
Do not refund SEPA payments until at least 7 days have passed from the time the donation was made, refunds can take up to 5 days to be fully processed.
We therefore record two FBR transactions: the 1st transaction is in pending status, and the 2nd is the success or reject. A thank you email will be sent out despite the transaction being pending.
The recurring day logs as the day of the submission.
| Form Field | Recommend form block field type | Description |
| Payment type | A Select that also includes card options (see above) | To take SEPA payments the value must be sepa_debit |
| Recurring Payment | Radio | To take recurring SEPA payments the value must be Y. If you submit anything else it will create as a single payment (FBS) |
| Recurring Frequency (if Recurring Payment = Y) |
Hidden field with default value | Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. |
|
Recurring Day |
Hidden field | The day of the month on which the recurring payment should be taken. (1-29 are allowed)
If you do not include this field, it will assume today as the day to take the monthly donations. (e.g. submitting on the 22nd would try on the 22nd the next month) |
In order to accept SEPA payments from IBANs from non-EU countries, the following additional fields are required for billing address details: City, Address Line 1, Postal Code, and Country. If those fields are not captured, the payment will fail with an error indicating the missing data. Please refer to Stripe details here for the specific countries for which these billing fields are required.
Processing iDEAL payments
If you wish to provide the ability to donate via iDEAL payments you will need to have enabled iDEAL in your Stripe account.
iDEAL is single payments only. There is no ability to do recurring through an iDEAL transaction.
How does it work?
When the payment type of iDEAL is chosen by the supporter (you can have a different label but the value must be this), an iDEAL Bank select field automatically appears after the payment type field for the supporter to select their bank.
You do not need to place an iDEAL bank field on the page – it will appear automatically!
When the bank is selected and the page submitted, it will redirect to the bank’s own page to complete the process, and then redirect back to the thanks page.
The payment is recorded as a FBS campaign type.
| Form Field | Recommend form block field type | Description |
| Payment type | A Select that also includes card options (see above) | To take iDEAL payments the value must be iDEAL |
Processing Bancontact
Required Fields for Bancontact Payments
For supporters in Belgium, you can set up the option to accept Bancontact payments.
Bancontact does not accept recurring donations at the moment. If you are accepting recurring payments for your Debit/Credit card processes, you may wish to hide these fields if the Bancontact payment type is chosen.
| Form Field | Recommend form block field type | Description |
| Email Address | Text with Email Validator | Email address identifying the supporter record |
| Payment Type | Select or Radio | BANCONTACT (case insensitive) should be used |
| Donation Amount | Text, Radio with Input or Select with Input with Donation Amount validator | May be entered as a whole number or number with two decimal places. Eg. Twelve Euro may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types. |
Processing Apple Pay and Google Pay (digital wallets)
Please look at this article for more information on enabling digital wallets with Stripe.
Processing ACH (U.S. only)
You may accept ACH payments (bank debits for the U.S.) through Stripe for both one-time and recurring transactions. To accept ACH through Stripe, you will leverage a Plaid integration on Engaging Networks.
Note: Stripe’s ACH implementation accepts payments from U.S. banking institutions only in USD. Additionally, your Stripe account must be connected to a U.S. (USD) bank. Canadian banks are not accepted through this flow.
How does it work?
Plaid acts as an intermediary layer to allow the supporter to search for and authenticate their bank details before sending and processing through Stripe.
Directly add ACH as a payment type option on any desired donation page using Stripe as the primary gateway. Please see below for the required field formatting. Stripe must
be set as the primary gateway on the page in order for ACH to be triggered (in the same way as required for SEPA and iDEAL payments).
When ACH is enabled as an option and a supporter selects to pay via ACH on the form, the prompt to search and link their bank details will appear
as a pop-up layer. Once the supporter securely selects their banking institution and enters their bank details, Plaid will confirm authentication, and the supporter will be directed back to the page to submit.
Note: Plaid supports most major banking institutions in the U.S. Some smaller banks and credit unions may not be available to link.
Required Fields for ACH
| Form Field | Recommend form block field type | Description |
| Email address | Text with email validator | Email address identifying the supporter record |
| Payment type | Select or radio | ACH (case sensitive) |
| Donation Amount | Text, Radio with Input, or Select with Input with donation amount validator | May be entered as a whole number or number with two decimal places. Eg. Twelve dollars may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types. |
Please find additional details on Stripe’s ACH processing through Plaid here.
Turning on webhooks
Some processes require webhooks to be enabled in your Stripe account. These allow us to receive data back from Stripe at a later date, for example delayed status updates. Follow these steps:
- In your Stripe account go Developers > Webhooks > Add endpoint
- Add endpoint
https://{DOMAIN}/page/stripe/webhookwhere {DOMAIN} is ca.engagingnetworks.app for those on the Canada data center or us.engagingnetworks.app for those on the U.S. data center.
- Add the following events:
charge.dispute.funds_withdrawn payment_intent.payment_failed payment_intent.succeeded payment_intent.canceled
Testing donation pages
Provided that you are using a gateway set up in test mode, you can use some dedicated card details to test payments. If you are testing with PSD2, then you will need to use different card details.
| Visa | 4242424242424242 |
| Card with 3D secure (PSD2) | 4000000000003220 |
| MasterCard | 5555555555554444 |
| Amex | 378282246310005 |
| Discover | 6011111111111117 |
| Diners | 30569309025904 |
| JCB | 3566002020360505 |
Your card expiry should be a future date. All other fields may take any valid value for testing.
You should not submit real credit card or bank account details to a test configuration.