Stripe

Your backend owns the payment

Carden's Stripe integration is a server-to-server API workflow. You create a Carden API key in the integration's Keys tab, prepare invoice enrichment, execute the Stripe request in your existing backend, and report what actually happened.

Create a scoped key

1. Select the correct merchant and environment in Carden.
2. Open the Stripe integration, then Keys. Create a named server key.
3. Grant enrichment:write and payments:write only if your service needs both. Stripe keys cannot grant QuickBooks integration scopes.
4. Store the key and Carden deployment base URL in backend secret configuration. Use a separate key for each service or environment.
5. Make a test enrichment request and a test payment report; inspect request IDs and the receiving environment.

The API derives organization and environment from authorization. Supplying a different invoice reference, Stripe account ID, or organization ID cannot broaden that access. See authentication.

Prepare and apply enrichment

Send a complete CanonicalInvoice to POST /api/v1/stripe/payment-intent-enrichment, or call the existing enrichment method in the private @carden/node workspace package. The response contains amount_details and payment_details for a supported Stripe PaymentIntent request.

Validate your Stripe API version and account support before applying these fields. The response is not a PaymentIntent and does not contain a charge result. Carden does not submit the payment for you or certify that Stripe transmitted the enhanced data to the network.

Preserve the original invoice version and x-carden-request-id. Record that value as enrichmentRequestId on a later report when you have it. Keep your own stable attempt ID before sending a request to Stripe.

Report the actual outcome

Post to /api/v1/stripe/payment-reports with a stable event ID, stable attempt ID, observed status, currency, amounts, occurrence time, and source. Include Stripe object IDs once known. Use sdk, merchant_webhook, or api to describe how the report was produced.

An authorization is authorized, not captured. A customer action requirement is requires_action, not a failure. A network timeout can leave the payment unknown; retrieve its state from Stripe or wait for a verified webhook before reporting a definitive outcome.

Reports are deduplicated by organization, integration, environment, and eventId. Deliver the same event with the same body when retrying. A later status is a new event for the same attempt. Keep capture and refund amounts cumulative for that attempt, rather than summing snapshots as new volume.

Handle later Stripe events

1. Receive Stripe webhooks in your existing merchant backend and verify them using Stripe's signature verification with the raw request body.
2. Resolve the event to your payment attempt and retrieve the current Stripe object when needed, especially for out-of-order notifications.
3. Normalize the status and cumulative amounts. Give this observation a new event ID and include providerEventId when available.
4. Persist the report before acknowledging your own processing, then deliver it to Carden with a scoped Carden key and source: merchant_webhook.

Carden authenticates the reporting key. It does not independently verify a merchant-submitted Stripe event with Stripe; a provider event ID and a source label are traceability, not provider verification.

Delivery and proof

A best-effort SDK call is not a delivery guarantee. Persist reports in a durable outbox, retry with backoff, alert on unresolved failures, and reconcile against your payment records. Report failure must never cause a second payment attempt.