Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Stripe integration handles payments, subscriptions, invoicing, and refunds in your Archie app. Once you connect it, Archie exposes a namespaced set of GraphQL queries and mutations (stripe_*) that your frontend, custom functions, and backend routes can call.
A typed TypeScript SDK for integrations is coming with the next archie-app release. This page documents the GraphQL operation surface available today.

​
Enable the integration

Open the Integrations module in the left sidebar and pick Stripe from the catalog. You’ll need from your Stripe dashboard:
  • Secret Key — starts with sk_test_ (test mode) or sk_live_ (production). Used by the backend to authenticate API calls.
  • Publishable Key — starts with pk_test_ or pk_live_. Safe to use in the frontend.
  • Environment — pick TEST while building, LIVE when you’re ready to take real payments.
  • Webhook Secret (optional) — whsec_.... Required if you want Archie to verify Stripe webhook signatures.
Archie encrypts the secret key with AES-256-GCM before storing it. Keys are scoped per project per environment, so test credentials on a development branch never touch production.

​
What you can do

The integration adds GraphQL operations for everything most apps need from Stripe:
  • Customers — stripe_customer, stripe_customers, stripe_createCustomer, stripe_updateCustomer, stripe_deleteCustomer
  • Payment intents — stripe_paymentIntent, stripe_paymentIntents, stripe_createPaymentIntent, stripe_updatePaymentIntent, stripe_confirmPaymentIntent, stripe_cancelPaymentIntent
  • Subscriptions — stripe_subscription, stripe_subscriptions, stripe_createSubscription, stripe_updateSubscription, stripe_cancelSubscription
  • Products and prices — stripe_products, stripe_createProduct, stripe_prices, stripe_createPrice
  • Invoices — stripe_invoice, stripe_invoices, stripe_payInvoice
  • Refunds — stripe_refunds, stripe_createRefund
  • Checkout sessions — stripe_createCheckoutSession for Stripe-hosted checkout
  • Billing portal — stripe_createBillingPortalSession for self-serve subscription management
  • Payment methods — stripe_paymentMethods, stripe_attachPaymentMethod, stripe_detachPaymentMethod
  • Webhook events — stripe_webhookEvents for inspecting signed events Archie has received
All list queries support cursor-based pagination via first and after.

​
Calling Stripe from your app

​
Create a customer

mutation {
  stripe_createCustomer(input: {
    name: "Ada Lovelace"
    email: "ada@example.com"
    phone: "+15551234567"
    metadata: { plan: "founder" }
  }) {
    id
    email
    createdAt
  }
}

​
Create a Checkout session

For Stripe-hosted checkout (the easiest path for most builders): 
mutation {
  stripe_createCheckoutSession(input: {
    mode: "subscription"
    customerEmail: "ada@example.com"
    successUrl: "https://yourapp.com/welcome"
    cancelUrl: "https://yourapp.com/pricing"
    lineItems: [{ priceId: "price_1ABC...", quantity: 1 }]
  }) {
    id
    url
  }
}
Redirect the user to the returned url. Stripe handles the payment and redirects to your successUrl when complete.

​
Open the billing portal

Let customers manage their own subscription: 
mutation {
  stripe_createBillingPortalSession(input: {
    customerId: "cus_..."
    returnUrl: "https://yourapp.com/account"
  }) {
    url
  }
}

​
Create a payment intent (manual flow)

If you want to render a custom checkout with Stripe.js or Stripe Elements: 
mutation {
  stripe_createPaymentIntent(input: {
    amount: 49.99
    currency: "usd"
    customerId: "cus_..."
    automaticPaymentMethods: true
  }) {
    id
    clientSecret
    status
  }
}
Pass the returned clientSecret to your frontend Stripe.js confirm step.

​
Webhooks

When you save the integration, Archie generates a webhook URL specific to your project and environment. Add it in the Stripe dashboard under Developers → Webhooks, and provide the resulting signing secret in the integration config. Archie verifies every incoming event before storing it. Query received events with stripe_webhookEvents, or react to them inside a custom function — see Webhooks. Common events you’ll likely care about:
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • customer.subscription.created / updated / deleted
  • invoice.paid / invoice.payment_failed
  • checkout.session.completed

​
FAQ

Archie selects credentials based on the environment your app is running in. Development environments use the keys saved with TEST; production uses the ones saved with LIVE. Setting up both up front means you can swap stages without touching code.
Yes. Use stripe_createPaymentIntent to get a clientSecret, then confirm it on the frontend with the publishable key. The publishable key is returned from the integration config and is safe to expose in client code.
Call stripe_createRefund with the paymentIntentId. Omit amount for a full refund or pass an amount for partial. Refunds start as pending and update to succeeded or failed once Stripe processes them.
Stripe retries failed webhook deliveries with exponential backoff for up to three days. Once your app is reachable, Archie verifies and stores the event normally. You can also replay events from the Stripe dashboard.
Yes. Add the stripe package to your custom function and call it with ctx.integrations.stripe.config.secretKey. The GraphQL operations cover most cases; the SDK is for anything they don’t expose.