Docs
Set-up Payments for Physical Goods and Services

Set-up Payments for Physical Goods and Services

Our templates manage payments for physical goods and services through Stripe.

atomsbox's templates provide you an implementation of Stripe that will allow your users to:

  1. Set-up card payments for later usage.
  2. Complete transactions choosing their payment method of choice.

Based on our current template catalog, you'll find payments with Stripe in:

Step-by-step Set-up

The codebase of the templates is ready to support payments. However, you will have to create a Stripe account and, then, connect the app and the backend server to your Stripe project.

Here is a step-by-step guide to help you with the setup of the credentials.

Before we get started

To integrate Stripe with your Flutter app, you will use three API keys:

  • Publishable Key: Used in the Flutter app to handle client-side operations. It is safe to expose in client-side code.
  • Secret Key: Used on the server-side for sensitive operations, such as charging a customer. It must be kept secure and not exposed in the client-side code.
  • Webhook Secret: Used on the server-side to verify the webhook messages sent from Stripe to your backend server.

IMPORTANT: It's crucial to safeguard the secret key to prevent unauthorized access to your Stripe account and customer data. If the Stripe secret key is leaked, those who have access to it will be able to access your customer data and process payment at their will.

Set-up your API Keys (Publishable and Secret Key)

  1. Create your account at stripe.com.
  2. Get your project's API keys from the Developers dashboard --> Click on Developers and then API Keys.

Stripe API Keys

Stripe gives you a test and a live environment. You should start using the test keys and once you're ready to deploy your app to production, move from the test to the live environment and replace your API keys to use the live production keys.

Once you have the two API keys, you'll have to update the .env files. There are two .env files, one at the root level of the project and another one in the /api directory. You should add the publishable key in the root level .env file as it will be used on the client-side.

Update the client-side .env

  • Add your publishable key --> "STRIPE_PUBLISHABLE_KEY=..."
  • Delete the env.g.dart file (path: lib/src/env/env.g.dart)
  • Run the following commands in the terminal:
# Clear the code generator cache 
dart run build_runner clean
 
# Run the code generator 
dart run build_runner build --delete-conflicting-outputs

Update the server -side .env

  • Add your secret key --> "STRIPE_SECRET_KEY=..."
  • Delete the env.g.dart file (path: api/lib/src/env/env.g.dart)
  • Run the following commands in the terminal:
# Navigate to the `api` folder
cd api
 
# Clear the code generator cache 
dart run build_runner clean
 
# Run the code generator 
dart run build_runner build --delete-conflicting-outputs

Set-up your Stripe webhook and the STRIPE_WEBHOOK_SECRET

As you're running your backend server on the localhost, you will have to test the webhook in a local enviroment, too. Therefore, go on the "Webhook" tab, and click on "Test in a local environment".

Stripe Webhook

  1. Download the Stripe CLI. Go and download the Stripe CLI from here
  2. Login into Stripe from the terminal
stripe login 
  1. Forward the webhooks event to your endpoint.
stripe listen --forward-to localhost:8080/api/v1/webhooks/stripe

Stripe Webhook Testing

As you enable the local testing for the webhook, you will see the webhook secret in your terminal. It will look something like: whsec_fa665e9545e3690913883366e5d9 ... ,

The webhook secret is required to protect the endpoint on the backend server that will receive the messages from Stripe. The reason is that the endpoint is public and anyone can send a request. Therefore, the first step is to validate that the request to the endpoint is signed with the webhook secret, and, actually comes from Stripe.

After getting the webhook secret, update the server -side .env again

  • Add your secret key --> "STRIPE_WEBHOOK_SECRET=..."
  • Delete the env.g.dart file (path: api/lib/src/env/env.g.dart)
  • Run the following commands in the terminal:
# Navigate to the `api` folder
cd api
 
# Clear the code generator cache 
dart run build_runner clean
 
# Run the code generator 
dart run build_runner build --delete-conflicting-outputs

If you have deployed your backend server to production as described on How to set-up the backend server, you can connect Stripe with your production webhook endpoint. In your Stripe dashboard:

  1. Click on "Add an endpoint"
  2. Enter your endpoint URL --> Your server base url + "/api/v1/webhooks/stripe"
  3. Choose which events to forward to the endpoint via the webhook --> 'customer.created', 'payment_method.attached', 'payment_method.detached', 'payment_intent.succeeded'.

Stripe Webhook Live