Getting started

Before you start

• An invitation or access to the correct Carden merchant organization.
• A QuickBooks Online administrator who can authorize the company connection, if QuickBooks is your invoice source.
• A merchant-owned backend that controls Stripe requests and receives Stripe webhooks.
• A durable database or queue for recording payment attempts and retrying report delivery.

1. Sign in and confirm the merchant

Use Carden's sign-in flow, powered by WorkOS AuthKit. Accept your team invitation with the intended account. In /dashboard, check the merchant name before connecting a provider or creating a key. If you are an authorized operator in /admin, select the client first.

If access is missing, ask an owner to check the invitation, membership, and permissions. Creating another sign-in does not grant access to an existing merchant's data.

2. Start in a non-production environment

Choose the test or sandbox environment exposed by the integration. Use QuickBooks sandbox data and Stripe test mode for validation. Store the Carden base URL and API key in your backend's secret configuration. A dashboard environment selector does not switch a running backend's credentials.

Confirm the environment on both the integration and the key. Follow the environment checklist before creating production reports.

3. Connect and review invoice data

1. Open the QuickBooks integration for this merchant and start the connection or send an invitation to the QuickBooks administrator.
2. Authorize the intended QuickBooks company through Intuit's OAuth consent screen.
3. Return to Carden and check the connection and invoice import status.
4. Review a source invoice: currency, line items, tax, shipping, balance, and purchase-order reference. Investigate missing values before enrichment.

A successful OAuth connection means access was granted; it does not mean every invoice imported or every invoice can be enriched. See the QuickBooks guide.

4. Create a Carden API key

Open the Stripe integration's Keys tab. Create a key for your backend and chosen environment. Grant enrichment:write for preparation and payments:write for payment reports. QuickBooks operations require a separate QuickBooks key with integration scopes. Give the key a name that identifies its service and environment.

Store the secret in a server-side secret manager. Keep it out of client-side JavaScript, browser storage, source control, screenshots, and logs. Use separate keys for separate services so you can revoke one without disrupting the others.

5. Prepare data, execute, then report

The @carden/node package is currently a private workspace package. Use the version supplied for your integration; these docs do not imply a public npm release. Its existing enrichment method returns Stripe fields without executing a payment.

import { Carden } from "@carden/node";

const carden = new Carden({
  apiKey: process.env.CARDEN_API_KEY!,
  baseUrl: process.env.CARDEN_BASE_URL!,
  timeoutMs: 5000,
});

// invoice is the complete CanonicalInvoice from your trusted invoice source.
const { enrichment, requestId } = await carden.stripe.createPaymentIntentEnrichmentWithRequestId({
  invoice,
  options: { taxRepresentation: "line_item", discountRepresentation: "line_item" },
});

// Persist requestId with your attempt; omit enrichmentRequestId if it is null.
// enrichment contains amount_details and payment_details, not a PaymentIntent.
// Merge these fields into your own supported Stripe request on your server.
// Keep Stripe authentication and payment idempotency in your existing backend.
// Persist and deliver the actual outcome separately with the payment-report API.

1. Use a complete canonical invoice to request enrichment. Stop or follow your approved exception policy if the data cannot be validated.
2. Merge the enrichment into your supported Stripe request. Keep Stripe authentication and payment idempotency in your own backend.
3. Record the actual attempt and observed outcome with a stable attempt ID. Persist an immutable report event in your durable outbox.
4. Send the event to POST /api/v1/stripe/payment-reports. Retry report delivery with the same event ID, without retrying the payment.
5. Verify Stripe webhooks in your own backend and report later authorizations, captures, refunds, failures, or cancellations as new events.

6. Verify before production

• Check that the expected merchant and environment received the test report.
• Send the same report twice and confirm the second response is a duplicate, not a second payment.
• Exercise failed payments, authentication-required states, partial refunds, and Stripe timeouts.
• Simulate Carden being unavailable and confirm your durable worker later delivers the report without creating another charge.
• Check logs using request IDs, then rotate any temporary setup key and deploy a production-scoped key through your normal approval process.