Set up Stripe's components

Your app shows the payment form, and Stripe handles the card. You never see the card number, and neither does Flowion.

1. Ask for a hold

From your backend, with the project's API key:

curl -X POST "$API/projects/$PROJECT/payments/holds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"chargingStationId": "'"$CHARGER"'", "payerReference": "order-8841"}'

chargingStationId is a charger of your project whose access is Paid, in the mode of your key. payerReference is optional: your own opaque reference for who is paying (an order, a basket, a user id in your system, at most 200 characters). Flowion keeps it with the hold and does not interpret it, so it is never a name or an email address. It defaults to the Idempotency-Key.

The answer is 201, and it carries what your page needs and nothing it must keep secret:

• holdId: the hold, for every later call.

• state: requires_action for a new hold: the payer has not confirmed it yet.

• clientSecret: Stripe's one-time secret for this hold. Pass it to the page and use it once.

• publishableKey: Stripe's publishable key. It is safe in a page.

• stripeAccountId: your organization's Stripe account.

• windowEndsAt: when the hold stops waiting for the session to start.

• amountMinor and currency: what is held, in the currency's smallest unit.

The Idempotency-Key is required. Send the same key when you retry a request that timed out, and you get the same hold back, never a second one, with its clientSecret again for as long as the payer has not confirmed it. Once the hold is authorized the secret is no longer returned, because it is of no use. Use a new key for a new hold.

2. Confirm it in your page

Load Stripe.js and create it with the publishable key and the connected account. The account matters: the hold lives on your organization's account, not on Flowion's.

const stripe = Stripe(publishableKey, { stripeAccount: stripeAccountId });

const elements = stripe.elements({ clientSecret });
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

// When the user presses Pay:
const { error } = await stripe.confirmPayment({
  elements,
  redirect: "if_required",
  confirmParams: { return_url: window.location.href },
});

confirmPayment shows the bank's approval step (3-D Secure) when the bank asks for it. error is Stripe's, shown to the user as it comes: a declined card, a wrong number.

3. Wait for the hold

Stripe tells the page the card was confirmed. Flowion learns it from Stripe separately, so read the hold from your backend until its state is authorized:

curl "$API/projects/$PROJECT/payments/holds/$HOLD" \
  -H "Authorization: Bearer $TOKEN"

The answer has the same fields as the hold you were given, minus every secret: state, amountMinor, capturedMinor and releasedMinor once something was taken, transactionId once a session exists, and the times. Do not start on the page's word alone. Start on the state.

4. Start the session

curl -X POST "$API/projects/$PROJECT/payments/holds/$HOLD/start" \
  -H "Authorization: Bearer $TOKEN"

The answer is 202 and means the start was sent. Only a hold that reads authorized starts: any other state is refused and sends nothing to the charger. The session is running only when a later read of the hold says started, so check for that before you tell the user to plug in, and check for a new session before you retry a start. Asking again for the same hold sends one start, not two.

5. Stop, and the receipt

Flowion stops the session at 85% of the hold. You can stop it sooner:

curl -X POST "$API/projects/$PROJECT/payments/holds/$HOLD/stop" \
  -H "Authorization: Bearer $TOKEN"

The answer is 202, and means the stop was sent. Only a hold that reads started has a session to stop: any other state is noOpenSession.

When the hold says captured, read the receipt and show it:

curl "$API/projects/$PROJECT/payments/holds/$HOLD/receipt" \
  -H "Authorization: Bearer $TOKEN"

What it holds is in Holds and what is taken.

The preview limit

The card is entered in your app, once per hold. Cards saved in Flowion Home are not available here, and the other way round. See the overview.