Skip to main content

Payment Workflow for Case Creation

This document explains how the payment part of the Case Create workflow works in the CV backend service.

A payment can be collected upfront before the case is created using CareValidate's supported payment providers (Stripe and NMI), or it can be collected by the partner organization's payment provider (Stripe, NMI, etc.), or it can be via Stripe Connect.

Overview​

When a new case is created, you can include payment information so that a user’s card/payment method is either saved for later use or charged immediately. The workflow supports two main payment providers integrated with CareValidate:

  • Stripe
  • NMI (Network Merchants, Inc.)

You include the relevant payment info in the case creation request depending on which provider and behavior you want.

CareValidate Stripe vs Customer Stripe vs Stripe Connected Account​

CareValidate Stripe​

CareValidate Stripe is a Stripe account that is owned by CareValidate. If you choose to use CareValidate Stripe, you will be provided with a Stripe publishable key for Staging and Production environments. Transactions made using this key will be processed by CareValidate Stripe. Disputes, refunds, etc. will be handled by the CareValidate Support team.

Customer Stripe​

Customer Stripe is a Stripe account that is owned by a customer. If the customer chooses to use their own Stripe account, they will handle the payment processing themselves and then call the Case Creation API to create the case. For added visibility to the CareValidate Support and Operations team, the customer will then need to call the Payment Confirmation API to confirm the payment after creating the case.

Stripe Connected Account​

To facilitate seamless payments and automated payouts, the platform utilizes Stripe Connect. This allows your organization to link its own Stripe account to CareValidate's "Master" account as a Connected Account.

How it Works for Partners​

This architecture creates a secure bridge between the platform and your business. Here is the high-level workflow:

Account Linking: You will go through a brief onboarding process to link your existing Stripe account (or create a new one) to the platform.

Direct Payouts: When a transaction occurs on the platform involving your services, Stripe automatically splits the funds. Your portion is sent directly to your Stripe account.

Data Security: CareValidate never sees or stores your sensitive banking information or credit card data. All sensitive data is handled by Stripe’s PCI-compliant infrastructure.

Financial Reporting: You retain access to your own Stripe Dashboard, where you can view your balance, manage payouts to your bank, and download tax documentation independently of the platform.

Benefits to Your Organization

  • Faster Access to Funds: No waiting for manual monthly checks; payouts are automated based on your Stripe settings.

  • Transparency: You have a real-time view of every transaction and fee within your own Stripe portal.

  • Operational Efficiency: Automated "split payments" eliminate the need for manual invoicing between organizations.

Stripe Setup Intents and Payment Intents​

Stripe supports two ways to handle payments in this workflow:

1. Setup Intent (save card for later)​

Use this when you want to collect the user’s card details now, but charge the card later.

  • The client generates a setupIntentId using Stripe.
  • This ID is sent with case creation.
  • Stripe validates and stores the user’s payment method.
  • No money is charged at this stage.

When to use:
✔ You want to save the card on file
✔ You plan to charge later (e.g., after review, approval, or fulfillment) ✔ You can also charge patient on signup using setup intents (configured in Organization settings)

2. Payment Intent (charge now and track status)​

Use this when you want to collect payment up front as part of creating the case.

  • The client generates a stripePaymentIntentId.
  • This represents a payment that is already created (and possibly confirmed).
  • Funds may be captured immediately or shortly after.
  • The backend can track the payment status using this ID.

When to use:
✔ You need to collect funds immediately
✔ You want payment tied directly to case creation ✔ You need to support BNPL as a method of payment

Choosing Between Setup and Payment Intent​

GoalUse
Save card for future chargessetupIntentId
Charge user immediatelystripePaymentIntentId
Support BNPLstripePaymentIntentId

Step-by-Step: Using setupIntentId with Stripe​

This section explains how to use Stripe Setup Intents to save a user’s card during case creation.

Step 1: Create a Setup Intent​

  • The frontend requests a new Setup Intent from your backend (or directly via Stripe if supported).
  • Stripe returns a setupIntentId and a client secret.

Purpose:
Prepare Stripe to securely collect and store card details.

Step 2: Collect Card Details on the Frontend​

  • Use Stripe’s UI components to collect the user’s card information.
  • Confirm the Setup Intent using the client secret.
  • Stripe validates the card and associates it with the Setup Intent.

Result:
The card is securely saved with Stripe, but no charge is made.

Step 3: Send setupIntentId During Case Creation​

  • When calling the Case Create endpoint:
    • Include the setupIntentId in the payment section.
  • The backend links this Setup Intent to the newly created case and user.

Sample payload for Case creation endpoint. The setupIntentId is passed in the payload as stripeSetupId

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "paymentDescription": "Description of what the patient purchased",
  "paymentAmount": 0.5,
  "stripeSetupId": "si_3SG0o8GkkQS2eXzh0BKpSaq0",
  "productBundleId": "<your-product-bundle-id>",
  "questions": [...]
}

Result:
The case is created with a saved payment method on file.

Step 4: Store Payment Method for Future Use​

  • The backend can retrieve the payment method linked to the Setup Intent.
  • This payment method is stored and associated with the case or user.

Important:
At this point, no payment has been collected.

Step 5: Charge the User Later (Optional)​

  • When you are ready to collect payment:
    • Collect the payment from the card information using the CareValidate Payment section in the Case details page.
  • The charge can happen days or weeks after case creation.

Common scenarios:

  • After case approval
  • After service completion
  • After manual review

NMI Payment Info​

If the case uses NMI instead of Stripe:

  • Payment info (such as a token or customer profile) is included during case creation.
  • The backend forwards this information to NMI.
  • NMI manages card storage and charging based on its own workflow.

NMI does not use Setup Intents or Payment Intents like Stripe.

This workflow allows flexible payment handling while keeping case creation simple and consistent.