> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe testing and operations

> Validate every Stripe attribution outcome and diagnose event delivery safely.

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.

## Recommended sandbox harness

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.

| Scenario               | Action                                              | Expected Biqli result                                                  |
| :--------------------- | :-------------------------------------------------- | :--------------------------------------------------------------------- |
| Signup                 | Create Stripe Customer and server-side signup lead  | One **Signed up** lead on the clicked link                             |
| One-time success       | Pay a registered `mode=payment` Checkout            | One sale for the paid amount                                           |
| Duplicate delivery     | Resend the delivered Checkout event                 | Sales and revenue unchanged                                            |
| Partial refund         | Refund part of the PaymentIntent                    | One negative activity item and reduced net revenue                     |
| Full refund            | Refund the remaining amount                         | **Refund completed**, net sale revenue zero                            |
| Paid subscription      | Complete registered `mode=subscription` Checkout    | One paid invoice sale, no duplicate Checkout sale                      |
| Free trial             | Complete a trial Checkout                           | One Stripe trial lead and no zero-value sale                           |
| Trial conversion       | End trial or advance a test clock                   | First non-zero invoice becomes one sale                                |
| Renewal                | Advance to the next billing cycle                   | One additional sale labeled as renewal                                 |
| Cancel at period end   | Set the cancellation flag                           | No new conversion; later renewals stop after cancellation takes effect |
| Immediate cancellation | Cancel the subscription                             | No new conversion and no reversal of paid revenue                      |
| Decline                | Use Stripe's documented decline test payment method | No sale                                                                |
| 3DS success            | Complete the authentication challenge               | One sale after verified payment                                        |
| 3DS failure            | Fail or abandon the challenge                       | No sale                                                                |
| Cancel URL             | Return without paying                               | No sale                                                                |
| Abandonment            | Leave Checkout open and do not pay                  | No sale; mapping eventually expires                                    |
| Delayed success        | Complete a supported delayed payment                | Sale only after `async_payment_succeeded`                              |
| Delayed failure        | Fail a supported delayed payment                    | No sale                                                                |

## 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

| HTTP result             | Meaning                                                                                                                  |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `200 processed`         | The supported event completed its handler. It may establish state, record a conversion, or record a non-revenue outcome. |
| `200 ignored`           | The event was valid but had no eligible conversion action.                                                               |
| `200 duplicate`         | This event ID already reached a terminal processed or ignored state.                                                     |
| `200 in_progress`       | Another request is currently processing the event.                                                                       |
| `500 processing_failed` | Processing failed. The event remains retryable with backoff.                                                             |
| `503 retry_later`       | A failed event is still inside Biqli's backoff window. The response includes `Retry-After`.                              |
| `400`                   | Signature verification or immutable event identity validation failed.                                                    |

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](/help/links/integrations/stripe/troubleshooting) for operator-facing recovery steps and [Store a Stripe Checkout Session](/docs/api-reference/conversions/store-stripe-session) for request-level errors.