Take card payments in your own app

Your app has its own users, and some of your chargers should charge them money. Flowion places a hold on the user's card before the session starts, starts the session, stops it before the cost passes the hold, and takes what was used when it ends. The money goes to your organization's own Stripe account. It never passes through Flowion.

What you need

• A Stripe account connected to your organization, able to take charges. Connect one and finish Stripe's onboarding.

• A hold amount. Every organization has one amount, the same for every charger, and you can change it. A change never touches a hold that is already placed.

• A charger whose access is set to Paid. See who may charge.

• A project API key that holds the settlement.payment.hold permission. The User policy at your project has it, so the key made for one project is enough, and an Admin key has it too. Every call here is made by your backend with the key, never from a browser, and a member's sign-in is refused on these routes. A sandbox key reaches sandbox chargers only.

The flow

1. Your backend asks Flowion for a hold with POST /v1/projects/{projectId}/payments/holds, naming the charger and sending an Idempotency-Key. Flowion answers with a clientSecret, a publishableKey and your organization's stripeAccountId.

2. Your app shows Stripe's Payment Element, and the user enters a card in your app. Stripe confirms it, and the bank may ask for the user's approval (3-D Secure).

3. Your backend reads the hold with GET /v1/projects/{projectId}/payments/holds/{holdId} until it says authorized.

4. Your backend starts the session with POST /v1/projects/{projectId}/payments/holds/{holdId}/start.

5. The session runs. Flowion stops it before the cost passes the hold. You can stop it yourself with POST /v1/projects/{projectId}/payments/holds/{holdId}/stop.

6. When it ends, Flowion takes what was used and releases the rest. The receipt is at GET /v1/projects/{projectId}/payments/holds/{holdId}/receipt.

The steps are written out, with code, in Set up Stripe's components. What Flowion does with the money at each step is in Holds and what is taken.

What a user can and cannot do

The user enters a card in your app, for each organization. A card a person saved in Flowion Home is not available to your app, and a card saved in your app is not available to Flowion Home. This is a deliberate limit of the preview: Stripe's components confirm a payment with a card the user types into your page, so there is no saved card shared across organizations here. If your app wants to remember a card between sessions, that is for your app and Stripe to arrange.

Where to go next

• Holds and what is taken: the amount held, the five-minute start window, the stop, the capture.

• Set up Stripe's components: the publishable key, the client secret and the Payment Element.

• Errors and states: every reason a request is refused, and what a hold's state means.

• Try it with test cards: a whole payment in a sandbox project, with no real money.