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). 

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

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.

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.

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.

Processing Bancontact

Required Fields for Bancontact Payments

For supporters in Belgium, you can set up the option to accept Bancontact payments.

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

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:

   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.

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