> For the complete documentation index, see [llms.txt](https://codehas.gitbook.io/the-repairbox/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codehas.gitbook.io/the-repairbox/stripe-integration.md).

# Stripe Integration

Stripe can be used to accept online payments for RepairBox invoices or other supported payment flows. The integration must connect a Stripe payment attempt to the correct RepairBox invoice/payment record and confirm the result from a trusted server-side source. A success page in the browser is not proof of payment.

The exact Stripe screens, supported payment methods, checkout flow, refund capabilities, tax behavior, and available settings depend on the deployed RepairBox version. This guide explains the configuration and control points to verify; it does not claim that every Stripe feature is already implemented.

Official references:

* Stripe Checkout: <https://docs.stripe.com/payments/checkout/quickstarts>
* Stripe webhooks: <https://docs.stripe.com/webhooks>
* Stripe API keys: <https://docs.stripe.com/keys>

## 1. Choose the supported payment flow

Depending on the installed integration, RepairBox may use a Stripe-hosted Checkout page, an embedded payment UI, or a custom payment flow. Prefer the flow implemented and maintained by the application rather than adding a separate payment form on top of it.

### Stripe-hosted Checkout

The server creates a Checkout Session using the invoice/payment context, then directs the customer to the Stripe-hosted payment page. This keeps card entry on Stripe's checkout experience. The server must still validate the amount and invoice and process trusted payment events.

### Embedded or custom checkout

Some Stripe flows display payment UI inside the site. They can provide a more integrated experience but require careful implementation of Stripe's client components, server APIs, payment state, and security. Use only if the deployed RepairBox adapter supports that mode.

### Payment links

A manually created Stripe Payment Link may be useful in some business workflows, but it is not automatically reconciled with a specific RepairBox invoice. Do not assume a manually issued link updates the invoice/payment record unless an explicit supported integration maps the provider event to that record.

## 2. Stripe credentials and environments

Stripe generally distinguishes publishable keys from secret keys and test mode from live mode.

* **Publishable key:** designed for client-side use when the selected flow requires it. It is not a substitute for authorization and should still be restricted to the proper environment.
* **Secret API key:** server-side credential used to create or inspect payment objects. Never place it in frontend code, public embed code, customer messages, Git, or screenshots.
* **Webhook signing secret:** verifies that incoming events came from Stripe and were not modified in transit. It is separate from the API secret key.
* **Test mode keys:** for test transactions and provider test methods.
* **Live mode keys:** for real charges and actual financial activity.

Configure the matching set for each environment. A test-mode secret key cannot create a live-mode payment. Do not copy test keys into production or live keys into a development environment.

Store secret keys in server-side environment variables or an approved secrets manager. Restrict who can view, rotate, and replace keys. If a secret is exposed, revoke/rotate it through Stripe and investigate recent activity.

## 3. Common configuration options

| Option                       | Purpose                                                       | Guidance                                                                              |
| ---------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Enable/disable Stripe        | Controls whether this payment method is offered               | Keep disabled until test transactions and webhook processing pass                     |
| Environment/mode             | Selects test or live processing                               | Confirm every key and webhook endpoint belongs to the same mode                       |
| Publishable key              | Initializes supported client-side Stripe components           | Use only in the supported flow                                                        |
| Secret key                   | Creates or retrieves Stripe payment objects server-side       | Store privately and grant minimal access                                              |
| Webhook signing secret       | Verifies event signatures                                     | Configure separately for each endpoint/environment as required                        |
| Default currency             | Currency of the invoice/payment request                       | Must agree with the RepairBox invoice and supported Stripe currency rules             |
| Payment method configuration | Controls which Stripe-supported methods may be offered        | Enable only methods supported by the integration, business, country and currency      |
| Success/return URL           | Destination after the customer leaves or completes a flow     | Must be an approved HTTPS URL; never use it as sole payment evidence                  |
| Cancel URL                   | Where the customer returns after cancelling a hosted checkout | Display a neutral status and let the customer safely retry if still appropriate       |
| Invoice/order reference      | Maps the provider operation back to RepairBox                 | Use a stable internal mapping or safe reference; do not trust a customer-submitted ID |
| Metadata                     | Adds limited reconciliation context to provider objects       | Avoid unnecessary personal data; server-generated references only                     |
| Webhook endpoint             | Receives payment events                                       | Keep public reachability while validating signature and event scope                   |
| Tax/discount handling        | Determines which system computes authorized totals            | Avoid charging tax/discount twice; define the system of record                        |
| Refund handling              | Allows a payment to be refunded, if supported                 | Check permissions, amount limits, reconciliation, and audit trail                     |

Some controls are managed in Stripe's Dashboard rather than in RepairBox. Confirm which choices are actually available in the installed version.

## 4. Connect an invoice to a payment session

A safe payment flow should use the server's invoice amount and currency. Recommended sequence:

1. An authorized customer opens an invoice or approved pay link.
2. The server loads the invoice and checks that the customer has access to it.
3. The server checks that the invoice is payable, calculates the outstanding amount using authoritative RepairBox totals, and excludes amounts already paid or otherwise settled.
4. The server creates the Stripe payment/Checkout Session using the validated amount and currency.
5. The application records the provider session or payment reference against the intended invoice/payment attempt.
6. The customer completes or cancels the provider checkout.
7. Stripe sends a signed event to the configured endpoint.
8. The server verifies the signature, checks the event and related payment object, and applies the state transition idempotently.
9. RepairBox updates the payment ledger and recomputes the invoice balance using its own rules.
10. A customer receipt or notification is sent only after the authoritative state has been recorded.

Never accept an amount from the browser as authoritative. A customer must not be able to change the amount by editing a request body or URL. Use server-side calculations, integer minor currency units where appropriate, and consistent decimal/currency precision rules.

## 5. Payment status and reconciliation

Keep the different states distinct:

* **Checkout opened:** customer has started the flow; no payment is confirmed.
* **Customer returned to success page:** the browser returned; verify the server/provider state before marking paid.
* **Provider payment succeeded:** trusted provider event or server-side verification confirms the relevant payment completed.
* **Processing/pending:** some payment methods complete asynchronously; do not mark paid early.
* **Failed or cancelled:** no successful payment should be recorded, though a separate attempt/history may exist.
* **Refunded or partially refunded:** preserve the original payment record and record refund movements separately according to the accounting model.
* **Disputed/chargeback:** track the provider state and reconcile it through an authorized workflow if supported.

A payment event must be tied to the correct RepairBox payment attempt and invoice. Ignore or flag events that refer to an unknown invoice, wrong currency, unexpected amount, duplicate provider payment, or an already-reconciled state.

Stripe documents asynchronous Checkout events; configure the event types that match the payment methods and flow used by this installation. Do not assume every payment method confirms synchronously.

## 6. Webhook configuration and verification

Configure the webhook endpoint that the RepairBox installation provides. In Stripe, select the relevant account and endpoint and subscribe to only the event types the integration handles.

Important controls:

* **Endpoint URL:** use the exact public HTTPS URL for the deployed environment.
* **Signing secret:** copy the signing secret for that particular endpoint; different endpoints/environments may use different values.
* **Subscribed events:** select events required by the code, not every event by default.
* **Signature verification:** verify the signed raw request using Stripe's supported library/method before trusting the payload.
* **Idempotency:** store event IDs or another appropriate processing key and ensure duplicate deliveries do not create duplicate payments or receipts.
* **Retry/acknowledgement:** process valid events reliably and respond appropriately; offload slow work to a queue when needed.
* **Monitoring:** capture safe event IDs and processing outcomes without logging secrets or unnecessary customer/payment data.

Do not trust an unsigned webhook body. Do not use an event name alone to assume a payment belongs to a specific invoice; verify the associated Stripe object and RepairBox mapping.

## 7. Tax, VAT, discounts and invoice totals

RepairBox's invoice, line items, taxes, discounts, and outstanding balance must have one authoritative calculation path. Stripe offers tax and discount capabilities in supported checkout products, but using them requires deliberate reconciliation. Do not apply a RepairBox discount and a Stripe promotion to the same amount unintentionally.

Before enabling any automatic Stripe tax or promotion feature, confirm:

* Which system calculates tax/VAT for the invoice.
* Whether the tax amount in Stripe must match an already-issued RepairBox invoice.
* Whether discounts/coupons are allowed for that customer and invoice.
* How rounding and minor currency units are handled.
* How refunds affect tax, discounts, invoice balance, and reports.
* Whether required billing address or tax identifiers are collected by the supported flow.
* Whether the business's jurisdiction and Stripe account are eligible for the selected feature.

If an invoice has already been issued with a fixed total, do not silently change the amount at checkout. Apply corrections through the approved invoice/credit-note process.

## 8. Refunds, partial payments and multiple attempts

The installed application may support only some of these workflows. Define them before turning on live processing.

* **Partial payment:** confirm that RepairBox can represent a remaining balance and multiple payment records without marking the invoice fully paid too early.
* **Repeated payment attempt:** avoid creating duplicate successful charges; reuse or replace checkout sessions according to the integration's design.
* **Expired checkout:** keep the invoice unpaid until a successful payment is confirmed; allow a new attempt only after validating the current balance.
* **Refund:** confirm the operator's permission, amount remaining refundable, reason/reference, provider result, and local ledger update.
* **Partial refund:** preserve the remaining captured amount and update the invoice/credit balance according to the accounting policy.
* **Dispute:** do not delete or overwrite the original payment. Track the provider case and reconcile the outcome separately.

Do not promise automatic refund support unless it is implemented and tested in the deployed version.

## 9. Security and PCI considerations

* Do not collect or store raw card numbers, CVCs, or other sensitive card authentication data in RepairBox.
* Use the supported Stripe-hosted or Stripe-compliant payment UI rather than building an unsafe card form.
* Verify invoice ownership/authorization before creating a payment session.
* Recalculate amount and currency on the server.
* Keep secret keys and webhook signing secrets private.
* Verify webhooks and process them idempotently.
* Use HTTPS on return pages and webhook endpoints.
* Keep logs minimal and access-controlled.
* Separate test and production data, keys, and webhook endpoints.
* Restrict access to refunds, payment settings, and financial reports by backend permission.
* Audit administrator changes to payment configuration and manual reconciliation.

## 10. Test mode launch plan

1. Configure test keys and a test-mode webhook endpoint.
2. Confirm a payable test invoice creates a Stripe session with the expected amount and currency.
3. Complete a Stripe test payment using the current test methods in the provider documentation.
4. Confirm the signed webhook is received and validated.
5. Confirm the correct RepairBox invoice/payment record changes state once.
6. Test cancellation, failed payment, delayed confirmation if supported, duplicate event delivery, and expired session.
7. Test mismatched amount, currency, customer, or unknown invoice handling in an authorized test environment.
8. Test multi-outlet invoices and discounts/tax scenarios supported by the product.
9. Test refund and partial-payment workflows only if implemented.
10. Review logs and financial reports against the provider dashboard.
11. Switch to live keys only after an approval checklist and a small controlled live transaction if appropriate.

## 11. Troubleshooting

**Checkout session cannot be created:** verify the correct API key/mode, account permissions, invoice state, amount/currency format, supported payment method, and provider API error.

**Customer sees success but invoice remains unpaid:** inspect the webhook delivery and signature verification, subscribed event types, job/queue errors, provider payment state, and invoice/payment mapping. Do not mark paid manually just because the return URL loaded.

**Payment succeeded but duplicate payment records appear:** review duplicate webhook delivery, retry handling, concurrent requests, and idempotency checks. Reconcile against Stripe before correcting ledger entries.

**Wrong amount or currency:** verify the server-side invoice calculation, tax/discount policy, currency precision, and whether a stale or already-paid invoice was used to create the session.

**Webhook returns an error:** verify endpoint reachability, secret for that exact endpoint, raw-body signature handling, supported API version, and application logs. Avoid logging secret headers.

**Refund does not reconcile:** check the provider refund status, payment mapping, refund amount, permissions, and whether asynchronous events must complete.

**Live payments fail while test payments work:** confirm live credentials, endpoint/secret for live mode, account onboarding, payment-method eligibility, business verification, and production URL/TLS.

## 12. Go-live checklist

* [ ] Stripe account and required payment capabilities are active.
* [ ] Test/live credentials and webhook secrets are separated.
* [ ] Secret API keys are never exposed to the frontend.
* [ ] Invoice ownership and payable amount are checked server-side.
* [ ] Currency, taxes, discounts and rounding reconcile with RepairBox.
* [ ] Success-page return is not treated as proof of payment.
* [ ] Signed webhooks are verified and processed idempotently.
* [ ] Failed, delayed, duplicated, and cancelled payment paths are tested.
* [ ] Refund/partial-payment behavior is explicitly defined or disabled.
* [ ] Financial permissions, audit logging and reconciliation checks are in place.
* [ ] Provider dashboard and RepairBox reports reconcile in test mode before launch.

## Related documentation

* Billing & Tax Settings
* Billing & Payments
* Webhooks and Notifications
* API Authentication
* Environment Variables
