How to Setup Stripe

Populate the following details:

• Name - Enter a Name to identify this Payment Gateway option.
• Run Mode - Select which Run Mode is operational on this Payment Gateway. Live makes for genuine transactions; until such a time the gateway goes live, Test Mode should be selected
• Publishable Key - The Publishable key from Stripe.
• Secret Key - The Secret key from Stripe. Secret API keys should be kept confidential and only stored on your own servers. Your account’s secret API key can perform any API request to Stripe without restriction.
• Webhook Signing Secret - The secret for the Webhook.
• Use Tax Rate For Subscriptions - When ticked affino will pass the Tax Rules External ID to Stripe. This ID need to be same as the Tax Rate ID in Stripe.
• Account Country - The two-letter country code of your Stripe account. Note: For UK accounts this is GB and not UK.

The following fields are used specifically for subscription-based products:

• Use Tax For Subscriptions - When ticked affino will pass the Tax Rules External ID to Stripe. This ID need to be same as the Tax Rate ID in Stripe.
• Use Coupons For Subscriptions - When ticked affino will pass the Coupon External ID to Stripe. This ID need to be same as the Coupon ID in Stripe

• Use Renewal Catalogue Item Price And Tax - Select to pass the Renewal Catalogue Item's External ID and Tax Rule External ID to Stripe if a Renewal Catalogue Item exists. If not selected, the Renewal Catalogue Item will still be used to generate the renewal order but Stripe will continue to renew on the existing price and tax rule. These IDs need to match ones in Stripe.

• Start Renewal Automation - Select to initiate the renewal automation scheduled task which will check for and generate subscription renewals.
• Start Cancellation Automation - Select to initiate the cancellation automation scheduled task which will check for subscription cancellations and cancel the payment at the payment gateway

Once you are happy with the configuration, enable the Live setting.

• Live - Tick to make this payment gateway active.

How to retrieve the Publishing Key and Secret Key

In your Stripe Dashboard Account, go to Developers > API Keys. Note: It is easier to seach for API Keys to find the correct screen.

Under the Standard Keys heading, you will see the Publishable Key and Secret Key. Copy-paste this into your Affino Payment Gateway.

How to retrieve the Webhook Signing Secret

Copy-paste the Webhook URL that is generated by Affino when you create your Stripe Payment Gateway.

In your Stripe Dashboard Account, go to Developers > Webhooks. Note: It is easier to search for Webhooks to find the correct screen.

Click the "Create an event destination" button. You should see a screen titled "Listen to Stripe events"

Under Endpoint URL, paste in the Webhook URL that was copied from Affino.

Webhook Events

Next select the webhook events that Affino will listen for. Click the "Select events" button

Search for the following events one by one and select them by clicking the "Add events" button

• charge.failed
• charge.succeeded
• charge.refunded
• customer.subscription.deleted
• subscription_schedule.canceled
• subscription_schedule.created

When you have added all the above events, click "Add Endpoint" button

You will be redirected to the main Webhooks screen. At the top you should see the following:

Status | Listening for | API Version | Signing secret | Configuration

Under Signing secret, click the reveal link to reveal the signing secret. You will need to copy-paste this back into the Webhook Signing Secret field within the Affino Payment Gateway, it should start with whsec_.

Stripe supports over 40 different payment methods, all seamlessly managed from a single interface. This gives you the flexibility to offer your customers a wide range of payment options, allowing them to choose the method that best suits their preferences, whether they're using a mobile device or desktop, many of the options available in their native country or specific to the bank they use. Available payment methods include Wallet Payments, Buy Now Pay Later, BACS Direct Debit, and many more.

To enable these payment methods:

Go to your Stripe Dashboard account.

Select Settings > Payments > Payment Methods or simply search for "Payment methods".

You will see listed the payment methods available to your account. These include:

• Credit Card options
• Wallets, e.g. Alipay, Apple Pay, Google Pay, Link (Stripe's own wallet payment), Paypal, etc
• Vouchers
• Bank redirects
• Buy now, pay later, e.g. Afterpay / Clearpay, Klarna
• Bank debits, e.g. BACS Direct Debit, SEPA Direct Debit
• Bank transfers
• Country-specific options

To enable each of these payment methods that you wish to receive payments from, click on the "Turn on" button

Note: Some options will require webhooks. Affino listen for 6 of these webhooks. See the Webhook Events panel to configure these within Stripe.

There is a simple pathway to upgrade an existing Payment Gateway using Stripe Card Element to the newer Payment Element API.

How to determine whether you are using Stripe Card Element

When editing the Payment Gateway, if the Payment Element panel displays the Test Security Groups and Switch To Payment Element settings, you are currently using the older Card Element API. As a result, only a limited set of payment options—credit card, Apple Pay / Google Pay, and Link—will be available on the frontend.

Testing the new Payment Element

First create a new Security Group and add any users that will be testing the Stripe Payment Element.

On the Payment Gateway select this Test Security Group.

Users who are in the new Security Group will see the Payment Element inteface when purchasing a product whilst other users will still see the old Stripe - Card Element.

This means you can test all your products on the Payment Element API before making it Live for customers.

Switching to the Stripe Payment Element API

Once you are happy with the testing, simple enable the Switch To Payment Element setting to switch all future payments at the Checkout to use the Stripe - Payment Element interface. Recurring renewals will not be affected and will continue to be renewed as they are. 

Note: This is a permanent switchover and cannot be reversed, i.e. the Gateway Type will be switched to use Payment Element API.

Stripe can be used as a traditional payment gateway, where the item price is sent directly to Stripe for a one-time payment. This is the simplest form of integration and does not support recurring payments. Affino also passes the user's name and email address along with the transaction to Stripe.

In this case, there is no need to set up a matching product catalogue item within Stripe and no External ID required to be entered into Affino.

• Affino: Control > Commerce > Catalogue Items
• Stripe: Dashboard > Product catalogue > All products

In order to sell a subscription in Affino with Stripe, you must first create a product in your Stripe dashboard:

On the Product catalogue screen, click the "Create product" button

Enter the following details:

• Name (required)
• Description (optional)
• Recurring | One-off (select either option)
• Amount (enter a price and currency)
• Billing period (select the billing period)

Click the "Add" button

Once the product has been created, copy-paste the product's Price ID. Note: It is the price_ i'd and not the prod_ id. If you cannot see the price_ id, click into the price details (under the Pricing heading) and then on the top right.

Copy-paste into Affino's Catalogue Item (External ID field). 

Note: If you have catalogue items with several prices (and currencies) you will need to:

• Use a single price/currency or
• Create a catalogue item, one for each price/currency

Currently, you will need to create a separate catalogue item, one for each price/currency (with a matching Stripe price id) as we do not have an External ID field in the Catalogue Item for each row within the price matrix to match each Stripe Price ID.

Please be aware that you will see multiple customer ID's in Stripe for each user in Affino. The reason for this is that, for every order, Affino creates a customer in Stripe and connects the card to the customer.

When the Use Tax Rate For Subscriptions option is ticked on the Payment Gateway, Affino will pass the External ID set on the Tax Rule to Stripe

This ID needs to be same as the Tax Rate ID in Stripe

Stripe: Product catalogue > Tax Rates

Affino: Control > Commerce > Tax Rules

If you are setting up a Subscription, then please bear in mind that you need to create a new Tax Rate in Stripe

In Stripe, click the "Click tax rate" button, enter the following details:

• Type (select VAT for UK)
• Region
• Rate (required)
• Include tax in price (select No)

Click the "Add tax rate" button

Note: Including tax in the price is not currently supported

Copy-paste the Tax Rate ID from Stripe to the Tax Rule External ID in Affino. The ID should begin with txr_:

Note: Tax in Stripe must be set up as Exclusive to match Affino.

Currently, Affino does not support Inclusive tax rates.

When the Use Coupons for Subscriptions option is ticked on the Payment Gateway, Affino will pass the External ID set on the Coupon to Stripe.

This ID needs to be same as the Coupon ID in Stripe.

Stripe: Product catalogue > Coupons

Affino: Control > Commerce > Coupons

To create a coupon in Stripe, click the "Create coupon" button

Enter the following details:

• Name
• ID (optional)
• Type (select Percentage off or Fixed amount off)
• Percentage discount/Discount amount
• Apply to specific products (optional)
• Duration (select Forever or Once)

Click the "Create coupon" button

Copy-paste the ID (under Details) to the Coupon's External ID field in Affino.

Note: The Multiple Months duration option is not supported

Enable the Use Renewal Catalogue Item Price And Tax setting on the Payment Gateway to pass the renewal catalogue item's External ID to Stripe to change the renewal order's price.

If not selected, the Renewal Catalogue Item will still be used to generate the renewal order but Stripe will continue to renew on the existing price and tax rule.

Note: These ID's need to match the ones in Stripe.

• Select the Start Renewal Automation settting to initiate the renewal automation scheduled task which will check for and generate subscription renewals

• Select the Start Cancellation Automation setting to initiate the cancellation automation scheduled task which will check for subscription cancellations and cancel the payment at the payment gateway.

If you have an existing Stripe setup, you may need to update the webhooks.

In the Stripe Dashboard, go to Developers > Webhooks

To update the webhooks Affino is listening for, click the three dots to the right of the Webhook URL and select the "Update details..." link.

Ensure the following events are selected:

• charge.failed
• charge.succeeded
• charge.refunded
• subscription_schedule.canceled
• subscription_schedule.created
• customer.subscription.deleted

Click the "Update endpoint" button

Affino currently listens to/monitors the following Stripe webhooks:

• `charge.failed`
• `charge.succeeded`
• `charge.refunded`
• `customer.subscription.deleted`
• `subscription_schedule.canceled`
• `subscription_schedule.created`

Please note that some actions are required when certain webhooks are received.

For the following webhooks:

• `customer.subscription.deleted`
• `subscription_schedule.canceled`
• `charge.failed`

-- you will need to check Stripe for any orders that were Cancelled, subscriptions that got deleted, or payments that didn’t go through during that period.

Once you’ve found the relevant orders in Affino, here’s what to do:

• If the payment status says "Paid Full" and there’s already a renewal order, just set that renewal order to "Cancelled"—this will automatically update the live subscription to "Cancel" as well.

• If it’s "Paid Full" but there isn’t a renewal order yet, set the current live subscription’s action to "Cancel" so that a renewal order won’t be created.

• If the order is still "Awaiting Payment Confirmation," just Cancel the order.

What happens when a payment goes through?

If you get a 'charge.succeeded' webhook, simply update the order in Affino to "Paid Full."

This process ensures that Affino remains in sync with Stripe regarding order and subscription statuses.

Affino supports both partial and full refunds that are issued within Stripe by listening for the charge.refunded webhook.

Issuing a refund in Stripe

Locate the order within Stripe by navigating to Transactions and selecting the payment item.

On the top right, click the "Refund" button and enter the following details. The refund amount can be a partial refund.

• Amount
• Reason
• Note

Click the "Refund" button

Checking the refund in Affino

On the Order within Affino, you will see the following refund details under Payment Details:

Refund Date | Amount | Tax | External Code | Refund Reason

You can edit edit the order if you wanted to update the refund amount and tax. Stripe allows for multiple partial refunds to be issued. This is reflected also in Affino. 

Note: You must ensure you have enabled the charge.refunded webhook within Stripe. See the Updating Webhook Events panel for more information.

Which reports show refunds?

The following reports detail refunds amounts. They are also available in the export files.

• Sales Invoice Report
• Sales Report
• Sales Target

Currently, Affino supports the following Stripe APIs for use with Stripe - Payment Element

• 2024-11-20.acacia
• 2024-06-20
• 2024-04-10

The following APIs are not yet supported, there are some changes in these versions of Stripe's API which will need to be updated within Affino, hence it is not advisable to update to these versions.

• 2025-03031.basil
• 2025-03-01.dashboard