Skip to content

Integration

Stripe Integration

Checkout, Payment Intents, subscriptions and Connect payouts, integrated so card data never reaches your systems and every order is created by a verified webhook.

Typical use cases
  • Ecommerce checkout with orders created from the completed session event
  • Subscription products where access is derived from subscription state
  • Deposits at booking with the balance charged to a saved method later
  • Marketplace payments with an application fee and supplier payouts
  • Invoice payment from a client portal

Overview

What this integration involves

Stripe is a payment processor. Sawhorse integrates with it. We are not a payment processor, we hold no PCI certification, and we do not build card processing infrastructure.

A Stripe integration has two halves. The first is collection: getting a payment method without the card touching your servers. The second, and the larger one, is the event pipeline that keeps your records and Stripe in agreement after money has moved.

Most integration defects live in the second half. A browser redirect is not a reliable signal that a payment succeeded, and a webhook that is processed twice creates a duplicate order. Both have well defined solutions and both have to be built deliberately.

Surface

Capabilities we use

  • Checkout Sessions

    A Stripe hosted payment page, created server side with the line items and metadata you need back later. It handles card entry, wallets, local payment methods, tax collection where configured, and 3D Secure. It is the fastest route to a compliant checkout and the right default unless the flow demands otherwise.

  • Payment Intents with Elements

    Where the checkout must live inside your own page, Elements renders processor controlled fields inside an iframe served by Stripe. Your page never has access to the card value. The Payment Intent tracks the lifecycle from creation through authentication to capture.

  • Setup Intents and saved methods

    Collecting a payment method without charging it, for deposits taken later, subscriptions starting after a trial, or card on file for a field service business. The resulting payment method is referenced by identifier, never by card number.

  • Subscriptions

    Recurring billing with plans, trials, proration on plan change, and billing cycle anchors. The subscription object carries the state your application derives entitlement from.

  • Connect and split payments

    Connected accounts for marketplaces and white label platforms. Onboarding collects the identity and payout information Stripe requires, charges can retain an application fee, and transfers settle the remainder to the supplier.

  • Refunds, disputes and payouts

    Full and partial refunds, dispute lifecycle with evidence submission, and payout reporting that lets you reconcile bank deposits against transactions and fees.

Data flow

Step by step

  1. 01

    Create the intent server side

    Your server creates a Checkout Session or Payment Intent with the amount calculated from your own data, never from a value supplied by the browser. Metadata carries your order or booking reference so the event can be matched later. The request sends an idempotency key derived from the business operation.

  2. 02

    Collect the payment method

    The customer is redirected to the hosted page or interacts with Elements in your page. Card details travel from the browser to Stripe. Your servers receive nothing but identifiers.

  3. 03

    Authenticate where required

    If the issuer or regulation requires 3D Secure, Stripe presents the challenge. The intent moves to a state requiring action and then resolves. Treating this as a normal branch rather than an error is what prevents avoidable declines.

  4. 04

    Receive the event

    Stripe posts a signed event to your endpoint. The handler verifies the signature over the raw body, checks the timestamp, stores the event by its identifier, and returns a success status immediately.

  5. 05

    Process from the stored event

    A worker reads the stored event and performs the business action inside a transaction: create the order, grant entitlement, submit fulfilment. Processing is keyed so a duplicate event is a no operation.

  6. 06

    Reconcile

    A scheduled job compares Stripe payouts, balance transactions and fees against your recorded transactions, and reports anything that does not match.

Architecture

How the pieces connect

Stripe integration data flow
  1. 01ApplicationtoStripe

    create intent

  2. 02BrowsertoStripe

    card details

  3. 03StripetoWebhook endpoint

    signed event. Asynchronous delivery.

  4. 04Webhook endpointtoEvent log

    store

  5. 05Event logtoProcessor

    process. Asynchronous delivery.

  6. 06ProcessortoPostgreSQL

    Application data exchange

Events

Webhooks we handle

  1. checkout.session.completed for orders created through a hosted checkout
  2. payment_intent.succeeded and payment_intent.payment_failed for direct payment flows
  3. invoice.paid and invoice.payment_failed to drive subscription entitlement and dunning
  4. customer.subscription.created, updated and deleted for plan state transitions
  5. charge.refunded to reverse fulfilment and adjust records
  6. charge.dispute.created and closed to open and resolve a dispute case
  7. account.updated on Connect, which signals when a supplier can receive payouts
  8. payout.paid for settlement reconciliation

Reliability

What makes it hold

  • Signature verification on the raw body

    The signature is computed over the exact bytes Stripe sent. Any framework that parses the body before your handler sees it will break verification, so the route is configured to receive the raw payload. Comparison is constant time, and the timestamp is checked against a short tolerance so a captured request cannot be replayed later.

  • Acknowledge fast, process after

    The endpoint stores the event and returns success within the delivery timeout. Doing the business work inline risks a timeout, which causes Stripe to retry, which causes duplicate processing on a system that is already slow.

  • Idempotent processing

    Each event is recorded by its Stripe identifier with a processed flag set inside the same transaction as the business action. A duplicate delivery finds the flag and stops.

  • Out of order delivery

    Stripe does not guarantee event ordering. Retrieve the relevant current object when needed, deduplicate event identifiers and apply guarded state transitions. Event creation timestamps are not a universal object-version mechanism and must not be treated as one.

  • Idempotency keys on requests

    Every write to Stripe carries a key derived from the business operation, so a retry after a network timeout returns the original object rather than creating a second charge.

  • Reconciliation as a backstop

    Webhooks can be missed. A scheduled job lists recent Stripe objects and compares them against local records, which catches anything the event pipeline lost.

Security

How it is secured

  1. Card data never reaches your servers, logs or database. Only identifiers and tokens are stored.
  2. Secret keys live in the platform secret store, scoped per environment, never in the repository.
  3. The publishable key is the only Stripe key present in client code.
  4. The webhook signing secret is distinct per endpoint and per environment.
  5. Amounts are always calculated server side from your own data.
  6. Restricted keys are used where a service needs only a subset of the API.
  7. Test and live environments are fully separated, including webhook endpoints and stored events.

Evidence

Where we have built this

FAQ

Questions people actually ask

Why not create the order on the success page?

Because the customer can close the tab, lose signal, or never be redirected. The payment still succeeded. The webhook is the only reliable signal, so it creates the order and the success page reads it.

What happens if our webhook endpoint is down?

Stripe retries with backoff over an extended window, so a short outage is recovered automatically. The reconciliation job covers anything that falls outside it.

How do you handle 3D Secure?

As a normal branch in the flow. The intent moves to a state requiring action, the customer completes the challenge, and the intent resolves. Treating it as a failure is how integrations produce avoidable declines.

Can we take payments in several currencies?

Yes. Stripe supports multi currency presentment and settlement. The design decision is which currencies you present and how prices are set in each, rather than a conversion at checkout.

How do marketplace refunds work after a payout?

The transfer is reversed where the connected account balance allows it, and otherwise creates a negative balance recovered from the next payout. The policy is agreed during design rather than during the first dispute.

Does using Stripe make us PCI compliant?

It reduces what applies to you by keeping card data out of your systems, which is significant. Your acquirer and, where required, a qualified assessor determine the validation route that applies. We build the architecture that supports the lightest applicable one.

Let’s talk about the system you need.

Tell us where the current process breaks down. We can map the workflow, examine the integration requirements and define a practical scope for the build.

Discuss Your Projectsupport@sawhorsesoftware.tech
  • A mutual NDA is signed before project details are shared.
  • Scope is fixed in writing before any build starts.
  • You own the source code, the IP and the documentation at delivery.
  • Support plans are available and tailored on a discovery or technical call.