Autonnel v1.7.0

Stripe

Configure Stripe in Autonnel: API keys, running test mode, wiring webhooks, and how upsells charge the saved card without a second checkout.


Stripe handles card payments with automatic SCA and 3DS support. You can run in test mode before going live with no code changes.

Prerequisites

  • A Stripe account. Use a Stripe test mode environment for sandbox testing — no separate account is needed.
  • Three values from your Stripe dashboard: publishable key, secret key, and webhook signing secret.
  • Your autonnel instance must be reachable from the public internet for webhooks to work. For local development, use a tunneling tool such as ngrok.

Setup walkthrough

1. Add a Stripe account

Go to Payment and click Add account under Stripe. Name the account.

2. Enter your keys

Fill in the following fields:

FieldWhere to find it
Publishable keyStripe dashboard → Developers → API keys → Publishable key
Secret keyStripe dashboard → Developers → API keys → Secret key
Webhook secretCreated in step 3 below

3. Wire the webhook

The account page shows a Webhook URL - copy it. In the Stripe dashboard:

  1. Go to Developers → Webhooks → Add endpoint.
  2. Paste the copied URL as the endpoint URL.
  3. Select the events you want to receive. At minimum, enable payment_intent.succeeded, payment_intent.payment_failed, and charge.refunded.
  4. After saving, reveal the Signing secret (whsec_...) and paste it into the Webhook secret field in autonnel.

Signature verification will fail if the secret is wrong or if any middleware re-parses the request body before it reaches the handler.

4. Save and verify

Save the account and make sure it is active. Then bind it: open Pages → Domains, click the domain, and on its Payment tab select the account in the Stripe row. A domain with no payment account bound cannot check out. Place a test order using a Stripe test card to confirm end-to-end flow.

Test mode

Stripe test mode uses keys prefixed with pk_test_ and sk_test_. The following test card numbers are reliable:

Card numberOutcome
4242 4242 4242 4242Payment succeeds
4000 0000 0000 0002Card declined
4000 0025 0000 3155Requires authentication (3DS)

Use any future expiry date, any 3-digit CVC, and any postal code.

Switching to live mode

  1. Open the account under Payment.
  2. Replace both keys with your live-mode keys (pk_live_..., sk_live_...).
  3. Create a new webhook endpoint in the Stripe dashboard pointed at the same URL, and replace the webhook secret with the live endpoint’s signing secret.
  4. Save. Stripe applies the new config immediately; in-flight payment intents that were created with test keys will fail — complete or cancel them before switching.

Refund flow

To issue a refund:

  1. Go to Orders, open the order.
  2. Click Refund, select full or partial amount, and confirm.

The refund is submitted to Stripe and the result is recorded automatically.

Amount handling

You enter amounts in major units (e.g., 29.99 USD). Autonnel converts them to the format Stripe requires automatically.

Public checkout requests

Customer-facing payment requests must include both orderId and trackingId. Autonnel treats the pair as the checkout flow capability and executes payment work in the order’s tenant context, so custom-domain routing cannot accidentally use another tenant’s Stripe configuration.

Brand on card statements

Card payments carry the sale domain’s store name (Pages → Domains → → Branding; a domain without one uses its host) as the statement_descriptor_suffix, so the statement reads like YOURPREFIX* SHOP B. Stripe allows 22 characters for the prefix, * and suffix together, so the suffix is reduced to Latin letters, digits and simple punctuation, capped at 10 characters, and upper-cased; a name with no Latin letter sends no suffix and the account default applies. The store name is also stored as metadata[brand] on the PaymentIntent. Set the shortened descriptor (prefix) in the Stripe Dashboard.

Caveats

  • Webhook reachability: The webhook URL must be publicly reachable from Stripe’s servers. Localhost URLs do not work in production; use ngrok or similar during local development.
  • API version pinning: Stripe may update its API version for your account over time. Pin a specific API version in Stripe dashboard → Developers → API version to avoid unexpected breaking changes.
  • Webhook body parsing: Stripe signature verification requires the raw, unparsed request body to reach the handler.
  • 3DS redirects are not supported: Cards that require a redirect-based 3DS flow will decline. Funnel pages do not support redirect-based flows.