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

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: For customers using ACH through Stripe, the following limits apply:

1. There is currently a limit of $999,999.99 USD and a minimum of $0.50 USD per transaction.
2. There is a limit of $6K daily or $10K in total transactions per week.

If you need higher limits, please reach out to Stripe support to get these updated.

Important: For customers using BACS or SEPA Direct Debit through Stripe, the following limits apply:

1. There is currently a limit of 10,000 EUR / 100,000 GBP per transaction.
2. There is a limit of 10,000 EUR / 10,000 GBP in total transactions per week.

If you need higher limits, please reach out to Stripe support to get these updated.

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. 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.deleted
   8. customer.source.expiring
   9. customer.source.updated
   10. payment_method.automatically_updated
   11. payment_method.detached
   12. radar.early_fraud_warning.created
   13. radar.early_fraud_warning.updated
   14. 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. Navigate to the Payments page in the left-hand navigation bar.
2. Select Fraud & Risk.
3. In Rules, enable Block if CVC verification fails.
4. Once you have everything you need, navigate to the Integrations page under the Admin section of gaiia.
5. Under the App directory tab, find the Stripe integration in the list and click the Install button.
6. Use the Select payment type step to define what type of payments you will support and click the Next button.
7. On the configuration step, enter all of the details that you captured from the steps above.
8. 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.