Connecting Stripe to Corinthian: A Step-by-Step Guide

Connecting Stripe to Corinthian: A Step-by-Step Guide

Stripe handles payments. Corinthian handles invoicing, delivery tracking, dunning, and team collaboration. Connecting them creates a closed loop: invoices go out through Corinthian, payments come in through Stripe, and both systems stay in sync automatically.

This guide walks through the entire setup process, from initial connection to verifying that payments sync correctly.

What the Integration Does

Before diving into setup, here's what connecting Stripe to Corinthian gives you:

Customer sync: Import your existing Stripe customers into Corinthian. No manual data entry. Customer records include names, email addresses, and metadata.

Payment tracking: When a customer pays a Stripe invoice or makes a payment through a Stripe checkout link, Corinthian updates the corresponding invoice status automatically. No manual reconciliation.

Payment links in invoices: Invoices sent through Corinthian can include Stripe-powered payment links. Customers click, pay, and the invoice is marked as paid -- all in one flow.

Automatic reconciliation: Payments received through Stripe are matched to open invoices in Corinthian. Exact matches happen automatically. Partial payments are recorded with remaining balances tracked.

Refund handling: When you issue a refund in Stripe, the corresponding invoice in Corinthian reverts to its appropriate status.

Prerequisites

Before you start, make sure you have:

• A Corinthian account with admin or owner permissions
• A Stripe account (Standard or Express) with API access enabled
• Access to your Stripe Dashboard with permissions to manage connected apps

If you're using Stripe in test mode for initial setup (recommended), you can complete the entire integration without processing real payments.

Step 1: Initiate the Connection from Corinthian

Navigate to Settings > Integrations in your Corinthian dashboard. Find the Stripe card and click Connect.

This initiates the Stripe Connect OAuth flow. You'll be redirected to Stripe's website where you'll authorize Corinthian to access your Stripe account.

What you're authorizing: Corinthian requests read access to your customers, invoices, and payment data. It also requests write access to create payment links and update invoice metadata. Corinthian does not get access to your Stripe balance, payouts, or bank account information.

Security note: The connection uses Stripe's OAuth 2.0 flow. Corinthian never sees or stores your Stripe secret key. The authorization produces a scoped access token that can be revoked at any time from your Stripe Dashboard.

Step 2: Authorize in Stripe

On the Stripe authorization page, you'll see:

• The specific permissions Corinthian is requesting
• Which Stripe account you're connecting (important if you have multiple)
• A confirmation button

Review the permissions and click Connect or Authorize.

After authorization, you'll be redirected back to Corinthian. The Stripe integration card should now show "Connected" with a green indicator.

If you manage multiple Stripe accounts: Make sure you select the correct account during authorization. Corinthian connects to one Stripe account per team. If you need to change which account is connected, disconnect first and reconnect with the correct account.

Step 3: Import Existing Customers

Once connected, Corinthian offers to import your existing Stripe customers. This is optional but recommended -- it saves you from manually recreating customer records.

Navigate to Settings > Integrations > Stripe > Import Customers.

What gets imported:

• Customer name
• Email address
• Stripe customer ID (stored for payment matching)
• Any metadata attached to the customer in Stripe
• Default payment method type (for reference)

What doesn't get imported:

• Payment method details (card numbers, bank accounts) -- these stay in Stripe
• Subscription details -- Corinthian tracks invoices, not subscriptions
• Stripe-specific billing settings

Handling duplicates: If a customer already exists in Corinthian with the same email address, you'll be prompted to merge or skip. Merging links the existing Corinthian customer record to the Stripe customer ID. Skipping leaves both records independent.

Import size: For accounts with more than 1,000 customers, the import runs in the background. You'll get a notification when it's complete.

Step 4: Configure Webhook Events

Webhooks allow Stripe to notify Corinthian in real time when events happen -- a payment succeeds, a payment fails, a refund is processed, etc.

Corinthian automatically configures the webhook endpoint during the OAuth connection process. You can verify the webhook is active in your Stripe Dashboard under Developers > Webhooks.

Events Corinthian listens for:

| Event | What It Does in Corinthian | |-------|---------------------------| | payment_intent.succeeded | Marks the matched invoice as paid | | payment_intent.payment_failed | Logs the failure and triggers dunning if configured | | charge.refunded | Reverts invoice status and records the refund | | customer.created | Creates or updates the customer record | | customer.updated | Syncs updated customer information | | invoice.paid | Marks the matched Corinthian invoice as paid | | invoice.payment_failed | Logs the failure for follow-up |

Testing webhooks: In Stripe's test mode, you can trigger test events using the Stripe CLI:

stripe trigger payment_intent.succeeded

Verify the event appears in Corinthian's activity log. If it does, webhooks are working correctly.

If webhooks aren't firing: Check that the webhook endpoint URL in Stripe matches what Corinthian registered. The URL should look like https://api.conduitt.io/webhooks/stripe/{your-team-id}. Also verify that the webhook signing secret matches -- Corinthian uses this to verify that events are genuinely from Stripe.

Step 5: Enable Payment Links on Invoices

With Stripe connected, you can add one-click payment links to every invoice you send.

Navigate to Settings > Invoice Defaults > Payment Options and enable Stripe Payment Link.

How it works:

1. When you create an invoice, Corinthian generates a Stripe-powered payment link
2. The link is embedded in the invoice email as a prominent "Pay Now" button
3. The customer clicks the link, enters their payment details in Stripe's hosted payment page, and pays
4. Stripe processes the payment and sends a webhook to Corinthian
5. Corinthian marks the invoice as paid and sends a receipt

Payment methods: The payment link supports whatever payment methods you've enabled in your Stripe Dashboard -- credit cards, ACH bank transfers, wire transfers, etc. You configure accepted payment methods in Stripe, not in Corinthian.

Currency handling: Corinthian creates the payment link in the currency specified on the invoice. Make sure your Stripe account supports the currencies you invoice in.

Step 6: Verify the End-to-End Flow

Before relying on the integration for real invoices, run through the complete flow in test mode:

1. Create a test invoice in Corinthian for a test customer
2. Send the invoice via email
3. Click the payment link in the email
4. Complete the payment using a Stripe test card (4242 4242 4242 4242, any future expiry, any CVC)
5. Check the invoice status in Corinthian -- it should show "Paid"
6. Check the payment details -- the payment amount, date, and Stripe payment ID should be recorded

If any step doesn't work as expected, see the troubleshooting section below.

Troubleshooting Common Issues

"Payment received in Stripe but invoice still shows unpaid in Corinthian"

Most likely cause: Webhook delivery failure.

Fix:

1. Check Stripe's webhook logs (Developers > Webhooks > Recent deliveries)
2. Look for failed deliveries to the Corinthian endpoint
3. If deliveries are failing, check that the endpoint URL is correct and your Corinthian team is active
4. You can manually retry failed webhook deliveries from the Stripe Dashboard

"Customer import shows 0 customers"

Most likely cause: The connected Stripe account has no customers in the current mode (test vs. live).

Fix: Make sure you're importing from the correct Stripe mode. If you connected in test mode, you'll only see test customers. Switch to live mode when you're ready to import real customer data.

"Payment link shows 'Invalid' when customer clicks it"

Most likely cause: Currency mismatch or the payment link has expired.

Fix:

1. Verify the invoice currency is supported by your Stripe account
2. Check if the payment link has an expiration set
3. Regenerate the payment link from the invoice detail page

"Webhook events are received but invoices aren't updating"

Most likely cause: The Stripe customer ID or invoice metadata doesn't match.

Fix: When Corinthian creates a payment link, it attaches the Corinthian invoice ID as metadata. If you're manually creating Stripe charges or payments outside of this flow, they won't match automatically. For manual payments, use Corinthian's manual payment recording feature instead.

"Authorization failed during OAuth"

Most likely cause: Your Stripe account doesn't have the required permissions or is restricted.

Fix:

1. Verify your Stripe account is fully activated (not in restricted mode)
2. Check that you have admin access to the Stripe account
3. If your Stripe account requires two-factor authentication, make sure you complete it during the OAuth flow
4. Try the connection in an incognito browser window to rule out session/cookie issues

Security Considerations

Token storage: Corinthian stores the Stripe access token encrypted at rest. The token is scoped to the specific permissions granted during authorization and can be revoked at any time.

Webhook verification: Every webhook event from Stripe is verified using the webhook signing secret. Events that fail verification are rejected and logged.

PCI compliance: Corinthian never handles card numbers or sensitive payment data. All payment processing happens on Stripe's PCI-compliant infrastructure. The payment link redirects customers to Stripe's hosted page.

Disconnecting: To revoke Corinthian's access to your Stripe account, go to Settings > Integrations > Stripe > Disconnect in Corinthian, or revoke access directly from your Stripe Dashboard under Settings > Connected Applications.

What Happens After Disconnecting

If you disconnect Stripe:

• Payment links on existing invoices will stop working
• New invoices won't include Stripe payment links
• Customer records in Corinthian remain (they're not deleted)
• Historical payment data stays in Corinthian (it was already recorded)
• Webhooks stop firing, so new Stripe payments won't update Corinthian

You can reconnect at any time. Reconnecting re-establishes the webhook and restores payment link functionality for new invoices.

Beyond Basic Integration

Once the connection is working, here are ways to get more out of it:

Dunning for failed payments: When Stripe reports a failed payment (declined card, insufficient funds), Corinthian can automatically start a dunning workflow. The customer gets a message asking them to update their payment method, with a link to do so.

Payment analytics: With Stripe data flowing into Corinthian, you can see payment trends alongside invoice data. Which customers consistently pay late? Which payment methods have the highest success rate? How does your average time-to-payment compare month over month?

Multi-currency reconciliation: If you invoice in multiple currencies, Corinthian tracks payment amounts in the original currency and converts to your base currency for reporting. The exchange rate at the time of payment is recorded automatically.

Connect Stripe to Corinthian now and close the loop between invoicing and payments.