Configure Stripe integration

Overview

Integrating Stripe within gaiia allows your customers to pay for their invoices by using either a credit card, bank payments using Automated Clearing House (ACH), bank payments using BACS Direct Debit (for UK customers) or bank payments using SEPA Direct Debit (for customers in Europe). Customers can also add a card with Apple Pay or Google Pay once digital wallets are enabled.

By default, bank payments will be disabled. To enable them, follow this guide: Enable bank payments for Stripe.

Additionally, you can also charge a fee to your customers for either credit card or bank payments. Check this article: Adding a processing fee for Credit Card and ACH payments.

Please Note: Ensure that the “Test mode” or “Sandbox” is not enabled when pulling the necessary information. Please also ensure that you do not point your Stripe test environment to your production instance. gaiia is able to provide a testing instance if you wish to test the webhooks.

Important: Stripe applies limits to bank payments (ACH, BACS Direct Debit and SEPA Direct Debit). Apart from the minimum below, these limits are set by Stripe on a per-account basis, so they differ between organizations and change as your account builds processing history. gaiia does not set or enforce them.

1. An ACH payment must be at least $0.50 USD. This minimum is fixed by Stripe and is the same for every account, so an invoice below it cannot be collected by ACH.
2. Find your account's other limits in your Stripe dashboard, under your account's payment method settings.
3. Contact Stripe support to have them reviewed or raised.

Beyond the minimum, limits apply at two levels: the size of a single payment, and the total your account can collect over a rolling period. A payment must satisfy both, so the lower one is what you will hit first. Because these are specific to your account, confirm them with Stripe rather than relying on figures quoted elsewhere.

When a payment falls outside one of these limits, Stripe rejects it and gaiia records the payment as failed with a reason of "Unknown" — the limit is not named in the failure. If a payment fails with no obvious cause, check the amount against your Stripe limits before investigating further.

Important: Depending on which payment methods you are using, it is extremely important to ensure you have the appropriate payment methods also turned on. To do this, please follow the steps below:

1. Navigate to Stripe's website.
2. Click on the Gear icon in the top right.
3. Select Settings.
4. Under Payments, locate Payment methods.
5. Under the Bank Debits section, select Turn on Cards, Turn on ACH Direct Debit (if using), Turn on BACS Direct Debit (if using) or Turn on SEPA Direct Debit (if using).

Steps

Setting up the Stripe integration involves four parts: preparing your API keys, configuring the webhook, finishing the setup in gaiia, and configuring your Radar fraud rules. Follow each section in order. A fifth, optional part enables Apple Pay and Google Pay.

A. Prepare your Stripe API keys

1. Navigate to Stripe's website.
2. Click on the Developers button in the lower-left corner.
3. Select the API keys tab.
   
4. In the Standard keys section, click on Reveal next to the following keys, and copy them in your message:
   • Publishable key

   • Secret key

     

5. Toggle the Test mode radio button in the upper-right corner.

   

   Some newer accounts don't have Test mode. Instead, click the account picker in the upper-left corner, then click Switch to sandbox.

   

6. Repeat step 5. Those test keys will be used for your gaiia sandbox instance.

7. Toggle off the Test mode radio button in the upper-right corner for your production instance.

   If you are in a sandbox, click the account picker in the upper-left corner, then click Exit sandbox.

B. Configuring the webhook

1. Select the Webhooks tab.
   

2. Click Add Destination.

   

3. Click on Select events, and select the following events:
   1. charge.dispute.closed
   2. charge.dispute.created
   3. charge.dispute.funds_reinstated
   4. charge.dispute.funds_withdrawn
   5. charge.dispute.updated
   6. charge.refund.updated
   7. customer.source.updated
   8. payment_method.automatically_updated
   9. radar.early_fraud_warning.created
   10. radar.early_fraud_warning.updated
   11. source.canceled
       
        

4. Optionally, if you are located in the US and need ACH - Direct debit support, located in the UK and need BACS Direct Debit support or located in Europe and need SEPA Direct Debit support, also add these events:

   1. payment_intent.canceled
   2. payment_intent.succeeded
   3. payment_intent.payment_failed
   4. setup_intent.canceled
   5. setup_intent.setup_failed
   6. setup_intent.succeeded
   7. setup_intent.requires_action
   8. checkout.session.completed
   9. mandate.updated
5. Select Webhook destination.
   

6. Set the Destination URL to: https://6bpu8a02c8.execute-api.us-east-1.amazonaws.com/production/on-stripe-webhook-event?billingSettingsId=gaiia billing setting ID

   

   Your gaiia billing setting ID can be found by navigating to gaiia's Settings (Admin) page > Billing tab > Settings > Currency Settings > scroll down to Other settings.

7. Confirm by clicking Add destination.

8. Copy the webhook Signing secret in your message by clicking Reveal.

   

9. Toggle the Test mode radio button in the upper-right corner, or if you are in a sandbox, click the account picker in the upper-left corner, then click Switch to sandbox.
10. Repeat steps 2 to 7 to configure the sandbox webhook.

C. Finishing the process

1. Once you have everything you need, navigate to the Integrations page under the Admin section of gaiia.
2. Under the Available tab, find the Stripe integration in the list and click the Install button.
3. Use the Select payment type step to define what type of payments you will support and click the Next button.
4. On the configuration step, enter all of the details that you captured from the steps above.
5. Click the Connect button to complete the process.

D. Configure Radar rules

To ensure proper fraud prevention and appropriate error handling, navigate to Payments → Radar → Rules and enable the following recommended rules.

These rules reflect gaiia's recommended baseline configuration. They can be adjusted based on your organization's risk tolerance and operational needs.

1. Enable Allow if payment matches one or more values in default Stripe allow lists.
2. Enable Block if :risk_level: = 'highest'.
3. Enable Block if payment matches one or more values in default Stripe block lists.
4. Enable Block if CVC verification fails.
5. Enable Block if Postal code verification fails.

These rules provide a strong default fraud protection setup and help reduce high-risk or unverifiable transactions, but they can be customized as needed.

E. Enable Apple Pay and Google Pay (optional)

Customers can add a card with Apple Pay or Google Pay in your checkout and client portal. To offer digital wallets, you need to turn them on in Stripe, register your domains in Stripe, and enable them in gaiia's Stripe integration.

Digital wallets are disabled by default, including on existing Stripe integrations. They are only available with the Credit card payment type. Customers only see the Apple Pay or Google Pay button on a supported device and browser, for example Safari with a card in Apple Wallet, or Chrome with a card saved in Google Pay.

Turn on the wallets in Stripe

1. In Stripe, click on the Gear icon in the top right and select Settings.
2. Under Payments, select the Payment methods tab.

3. Under For your platform account, select the Default configuration.
   

   gaiia uses your account's default payment method configuration, so the wallets must be turned on in that one.

4. Make sure Apple Pay and Google Pay both show "Enabled". If either shows "Disabled", open it and turn it on.
   

Register your domains in Stripe

Apple Pay and Google Pay only appear on domains registered in Stripe. Register both your checkout domain and your client portal domain.

1. Select the Payment method domains tab.
2. Click on Add a new domain.
   
3. Enter the full address of your checkout, for example https://www.order.myisp.com, and click on Save.
   

4. Repeat steps 2 and 3 for the full address of your client portal.

   If your checkout or client portal can be reached both with and without www., add both addresses.

5. Toggle the Test mode radio button, or switch to your sandbox, and repeat these steps with the checkout and client portal addresses of your gaiia sandbox instance.

Enable digital wallets in gaiia

1. Navigate to the Integrations page under the Admin section of gaiia.
2. Under the Installed tab, open the Stripe integration.

3. In the configuration, check Digital wallets enabled.

   If you have more than one Stripe configuration, for example one per currency, enable it on each configuration where you want to offer digital wallets.

4. Save your changes.