The Stripe Payment Gateway

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:

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

Additional fields required for card payments

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.

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.

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.

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.

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.

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

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:

1. In your Stripe account go Developers > Webhooks > Add endpoint

2. Add endpoint https://{DOMAIN}/page/stripe/webhook where {DOMAIN} is ca.engagingnetworks.app for those on the Canada data center or us.engagingnetworks.app for those on the U.S. data center.

3. Add the following events:

   CODE

   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.

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.

You should not submit real credit card or bank account details to a test configuration.

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