Stripe API usage

Add enrichment to your existing Stripe request

Keep your checkout and merchant-owned Stripe client. Automatic source-backed preparation (HTTP API only) returns data.mode, data.enrichment, data.optimizationIssues, and preparation, with a diagnostic x-carden-request-id header. Enhanced mode supplies validated commercial fields. Ordinary mode supplies null enrichment and bounded optimization issues for review; it sends a normal payment without enhanced fields and earns no Carden verified optimization savings or fee. The preparation API only returns data; it does not call Stripe.

Prepare a linked invoice for Stripe

Automatic preparation is an HTTP API; call it from your backend with any HTTP client. A linked-invoice key needs invoices:read and enrichment:write. Supply exactly one invoiceId, quickbooksInvoiceId, or invoiceNumber, the exact full unpaid amount and currency, and a stable preparation idempotency key. expectedRevision is optional. You can pass invoiceId without retrieving the invoice first. POST /api/v1/stripe/payment-preparations/from-invoice chooses enhanced or ordinary mode without a fallback toggle. Invoice ready remains the unchanged enhancement-readiness flag; it is not an automatic-payment authorization.

POST /api/v1/stripe/payment-preparations/from-invoice HTTP/1.1
Host: www.cardenpay.com
Authorization: Bearer <CARDEN_API_KEY>
Content-Type: application/json
Accept: application/json

{
  "invoiceId": "<INVOICE_ID>",
  "amountMinor": 11300,
  "currency": "usd",
  "idempotencyKey": "prepare_attempt_1042_1"
}

{
  "object": "stripe.payment_preparation",
  "api_version": "v1",
  "data": {
    "mode": "enhanced",
    "enrichment": {
      "payment_details": {
        "order_reference": "INV-1042"
      },
      "amount_details": {
        "enforce_arithmetic_validation": true,
        "line_items": [
          {
            "product_name": "Industrial filters, boxed",
            "product_code": "FILTER-01",
            "unit_cost": 5000,
            "quantity": 2,
            "unit_of_measure": "box"
          }
        ],
        "tax": {
          "total_tax_amount": 800
        }
      }
    },
    "optimizationIssues": []
  },
  "preparation": {
    "id": "44444444-4444-4444-8444-444444444444",
    "invoiceId": "11111111-1111-4111-8111-111111111111",
    "snapshotId": "22222222-2222-4222-8222-222222222222",
    "revision": "invoice-revision-example-3",
    "sourceIntegrationId": "33333333-3333-4333-8333-333333333333",
    "sourceConnectionId": "quickbooks_connection_example",
    "checkedThrough": "2026-01-01T11:59:00.000Z",
    "createdAt": "2026-01-01T12:00:00.000Z",
    "amountMinor": 10800,
    "currency": "usd"
  }
}

{
  "object": "stripe.payment_preparation",
  "api_version": "v1",
  "data": {
    "mode": "ordinary",
    "enrichment": null,
    "optimizationIssues": [
      {
        "code": "missing_product_code",
        "path": "lineItems[0].productCode",
        "message": "Confirm the authoritative product code before optimizing.",
        "category": "mapping"
      }
    ]
  },
  "preparation": {
    "id": "44444444-4444-4444-8444-444444444444",
    "invoiceId": "11111111-1111-4111-8111-111111111111",
    "snapshotId": "22222222-2222-4222-8222-222222222222",
    "revision": "invoice-revision-example-3",
    "sourceIntegrationId": "33333333-3333-4333-8333-333333333333",
    "sourceConnectionId": "quickbooks_connection_example",
    "checkedThrough": "2026-01-01T11:59:00.000Z",
    "createdAt": "2026-01-01T12:00:00.000Z",
    "amountMinor": 10800,
    "currency": "usd"
  }
}

Branch only on the validated mode. Include commercial fields when enhanced; omit amount_details and payment_details entirely when ordinary. Use preparation.amountMinor and preparation.currency unchanged and retain preparation.id as metadata.carden_preparation_id in both modes. The x-carden-request-id response header is diagnostic only. The original POST /api/v1/stripe/payment-intent-enrichment/from-invoice endpoint remains strict enhancement-only and unchanged.

Attach the fields to the real Stripe call

These are before-and-after versions of the same invocation, not two calls to run. stripe is your configured Stripe client. existingPaymentIntentParams and existingStripeRequestOptions contain your checkout's current amount, currency, customer, payment method, confirmation and capture settings, metadata, idempotency key, and account routing.

const result = await stripe.paymentIntents.create(
  existingPaymentIntentParams,
  existingStripeRequestOptions,
);

After preparing the invoice above, use the returned mode to construct the arguments for that same request. Keep existingStripeRequestOptions, including the merchant's account routing and provider idempotency key, unchanged.

const { mode, enrichment, preparation } = prepared;
const { payment_details: existingPaymentDetails, ...paymentParams } = existingPaymentIntentParams;
const result = await stripe.paymentIntents.create({
  ...paymentParams,
  ...(mode === "enhanced" && enrichment ? {
    ...enrichment,
    amount_details: {
      ...enrichment.amount_details,
      line_items: [...enrichment.amount_details.line_items],
    },
    payment_details: { ...existingPaymentDetails, ...enrichment.payment_details },
  } : {}),
  amount: preparation.amountMinor,
  currency: preparation.currency,
  metadata: {
    ...existingPaymentIntentParams.metadata,
    carden_preparation_id: preparation.id,
  },
}, existingStripeRequestOptions);

For enhanced mode, the line_items copy adapts Carden's read-only TypeScript array to Stripe's mutable request type. Ordinary mode removes enhanced fields, including pre-existing amount_details and payment_details. Both modes retain checkout settings and existing metadata while adding the stable preparation ID. Reconcile source tax, discounts, shipping, and totals before payment; Carden never invents them.

Stripe payment reports are optional observations

POST /api/v1/stripe/payment-reports remains available for integrations that already submit observations. It is optional and not required to confirm a payment or to verify capture or settlement. Carden receives actual Stripe captured and refunded payment evidence through signed webhook deliveries. Webhook delivery verification alone does not confirm capture.

POST /api/v1/stripe/payment-reports HTTP/1.1
Host: www.cardenpay.com
Authorization: Bearer <CARDEN_API_KEY>
Content-Type: application/json
Accept: application/json

{
  "eventId": "report_attempt_1042_captured_1",
  "attemptId": "attempt_1042_1",
  "status": "captured",
  "currency": "usd",
  "amountMinor": 11300,
  "capturedAmountMinor": 11300,
  "refundedAmountMinor": 0,
  "occurredAt": "2026-01-01T12:00:00.000Z",
  "source": "api"
}

Webhook delivery is asynchronous and webhook setup does not import historical charges or itemized fee reports. Preparation, metadata, and any optional merchant observation do not by themselves establish enhanced-data qualification, network qualification, settlement, or verified savings.

Handle preparation and evidence errors

• Keep Carden and Stripe secrets out of browser bundles and logs.
• Use test mode before production.
• Keep preparation, actual payment activity, network qualification, and verified savings separate.