Skip to main content
Test the complete path in a Stripe sandbox before enabling live traffic. Unit tests confirm invariants, but only an end-to-end Checkout proves that browser attribution, account connection, Stripe delivery, customer identity, and reporting work together. Use a dedicated external consumer application that behaves like a real merchant integration:
  • public browser SDK with a sandbox workspace publishable key;
  • allowed test hostname;
  • private Biqli workspace API key on the server for signup leads;
  • Stripe sandbox secret key on the server for customers, Checkout, refunds, and test clocks;
  • the Biqli Stripe App installed and connected in the same Stripe sandbox account;
  • a conversion-enabled short link targeting the harness.
The browser must never receive either secret key. Protect lifecycle controls such as refund, cancel, end-trial, and advance-clock actions with a separate harness access token or authenticated test session.

​
Test matrix

Run each scenario with a fresh Checkout Session. Use a fresh click and customer when the scenario tests acquisition identity.

​
Verify evidence at every layer

For each test, retain non-secret identifiers:
  • Biqli bq_id;
  • Stripe Checkout Session ID;
  • Stripe Customer ID;
  • subscription, invoice, PaymentIntent, charge, and refund IDs when applicable;
  • Stripe event ID and delivery status;
  • Biqli request ID returned by browser or server tracking calls;
  • final Biqli customer counts, activity, and net revenue.
Do not paste complete event payloads containing customer data into public issues. Redact personal and secret data before sharing diagnostics.

​
Expected event-delivery statuses

The retry delay starts at 15 seconds and grows exponentially to a maximum of one hour. A processing claim becomes recoverable if it remains stale for the configured processing window.

​
Event-order recovery

Checkout, subscription, invoice, and refund events are independent deliveries. The app handles expected reordering without weakening attribution:
  • early trial or invoice events can wait for a pending Checkout mapping;
  • an early successful refund waits for the original sale;
  • completed object mappings are immutable for exact identities;
  • duplicate terminal events return successfully without repeating effects;
  • the same event ID with materially changed data is rejected.
When an early event fails once and a later prerequisite succeeds, allow Stripe’s automatic retry. Use Resend only after the prerequisite delivery is processed and only for the original failed event.

​
Distinguish processed and a conversion

processed means the event handler completed successfully. It does not always mean a new lead or sale was created. Examples that can process without increasing revenue include:
  • an unpaid Checkout whose mapping was established;
  • a zero-value invoice;
  • a refund status transition that is not yet successful;
  • an idempotent repeat represented by another supported event type.
Always verify the customer activity and totals, not only the webhook HTTP code.

​
Live rollout

After sandbox validation:
  1. install the live version of the Biqli app in the intended live Stripe account;
  2. connect the live account to the production Biqli workspace;
  3. use the live Stripe account ID and stripe_environment: 'live' in your browser registration;
  4. use the production hostname and workspace publishable key;
  5. confirm the live event destination receives the selected 11 events;
  6. run a low-value live payment and refund;
  7. compare the Stripe object IDs, Biqli customer activity, and net revenue;
  8. monitor failed deliveries during the initial rollout.
Sandbox and live connections, object IDs, webhook secrets, and API credentials are not interchangeable.

​
Operational security

  • Rotate a compromised Stripe or Biqli secret immediately.
  • Revoke unused publishable keys and remove obsolete allowed hostnames.
  • Disconnect workspace authorization when account ownership changes.
  • Uninstall the app in Stripe when the integration is no longer used.
  • Keep webhook and OAuth logs free of raw credentials.
  • Grant Stripe permissions only through the official app installation screen.
  • Never ask support to accept a secret key as diagnostic evidence.

​
Troubleshooting order

  1. Verify the Biqli click exists.
  2. Verify the hostname and publishable key belong to the connected workspace.
  3. Verify exact Checkout registration succeeded.
  4. Verify account and environment match.
  5. Verify Stripe payment or invoice status.
  6. Verify the selected event reached the correct destination.
  7. Interpret the Biqli response status and retry timing.
  8. Verify customer activity and net revenue.
See Troubleshoot the Stripe App for operator-facing recovery steps and Store a Stripe Checkout Session for request-level errors.