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 payment will be disabled. To enable them, follow this guide , and then follow these steps: 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 should be noted:

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 should be noted:

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

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

   

   Note: 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

   Note: 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.expiring
   8. customer.source.updated
   9. payment_method.automatically_updated
   10. radar.early_fraud_warning.created
   11. radar.early_fraud_warning.updated
   12. 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 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 from 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.