The Stripe Payment Gateway
- Michael Kalnicki
- Daniel Sewe
- Noelle Butler
- Sam Louk
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).
It is recommended that you 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.
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
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.
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 = card |
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 | 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 left blank, subsequent transactions will process on the same day as the initial transaction. |
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.
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 | 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) |
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.
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.
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.
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.
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. |
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 charge.dispute.closed 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.
Testing ACH Transactions
To test Plaid’s ACH functionality, choose any bank from the Plaid pop-up after clicking “Link Account”. From there, Plaid will direct you to a sandbox bank titled First Platypus Bank. Enter the following credentials:
Username: user_good
Password: pass_good
If it prompts you for 2 Factor Authentication, ensure “Mobile” is selected and click “Get Code”. Then enter any value for the 2FA code requested.
Continue through the prompts. When you are returned to the Engaging Networks page, you should see the text “Account Linked”.
Submit your donation from there.
These test transactions will have payment type “TEST: ach” on the supporter record.
Note that a test gateway must be assigned to the page to use Plaid’s sandbox functionality.
Stripe Radar
Stripe Radar provides real-time fraud protection and is available to every Stripe account.
Engaging Networks uses the following integration types with Stripe that provide very good to excellent Radar integration quality:
Stripe Elements with Customer signals.
Direct API integration with Client and Customer signals.
Stripe.js library in payment page, which is needed for the advanced fraud signals.
Since Radar collects information on anomalous device or user behavior that might be indicative of fraud, please make sure that your own privacy policy tells your customers about this type of collection. Please visit this page for more info: https://docs.stripe.com/radar/integration