This document explains how to configure and use the Stripe Payment Gateway Addon within the KiviCare Clinic Management System. It is intended for administrators who want to accept card payments directly during appointment booking.
Overview
The Stripe Payment Gateway Addon allows clinics to accept credit and debit card payments seamlessly within the KiviCare booking flow.
The integration uses Stripe Checkout (Embedded Mode), ensuring:
Secure card handling
PCI compliance via Stripe
A smooth, in-page payment experience for patients
Prerequisites
Before configuring Stripe, ensure the following requirements are met:
KiviCare Stripe Addon
The Stripe Addon must be installed and activated.
Stripe Account
A valid Stripe account created at stripe.com.
SSL Certificate
Your website must use HTTPS (required by Stripe).
Stripe Configuration in KiviCare
Step 1: Navigate to Payment Settings
Log in to your WordPress Admin Dashboard.
Go to KiviCare > Settings > Payment Settings.
Step 2: Enable Stripe Gateway
Locate Stripe in the list of available payment gateways.
Toggle the Enable switch (Green).
Click Manage (or the edit icon) to open Stripe settings.
Step 3: Configure Stripe Settings
Fill in the following fields:
Enable Stripe Must be checked to activate Stripe payments.
Mode Must be checked to activate Stripe payments.
Sandbox (Test) – For testing payments
Live – For real transactions
Secret API Key Enter your Stripe Secret Key (starts with sk_).
Publishable Key Enter your Stripe Publishable Key (starts with pk_).
Currency Choose the currency in which payments will be processed (e.g., USD, EUR, INR).
Step 4: Save Settings
Click the Save button to apply and store your Stripe configuration.
How to Obtain Stripe API Keys
Follow these steps to retrieve your Stripe API keys:
Log in to the Stripe Dashboard.
Navigate to Developers > API Keys.
Test Mode Keys
Enable Test Mode using the toggle at the top-right.
Copy the Publishable Key (e.g., pk_test_...).
Reveal and copy the Secret Key (e.g., sk_test_...).
Live Mode Keys
Disable Test Mode.
Copy the Publishable Key (e.g., pk_live_...).
Reveal and copy the Secret Key (e.g., sk_live_...).
Important: Test keys work only in Sandbox mode, and Live keys work only in Live mode.
Payment Flow
Patient books an appointment.
Patient selects Stripe as the payment method.
Stripe Checkout (Embedded Mode) loads securely on the booking page.
Patient enters card details and completes payment.
Upon successful payment:
Appointment status is updated to Confirmed.
Payment details are stored in KiviCare.
If payment fails or is cancelled, the appointment remains Cancelled.
Stripe Webhook & Signing Secret Configuration
1. Introduction
The Stripe Webhook integration allows KiviCare to receive instant updates from Stripe when a payment is processed. This is essential for ensuring that appointments are confirmed immediately, even if a user’s browser crashes or they close the payment window prematurely.
The Webhook Signing Secret is a security feature that verifies each message sent by Stripe, protecting your system from fraudulent payment notifications.
2. Configuration Guide
Step 1: KiviCare Setup
Log in to your WordPress Admin Dashboard.
Navigate to KiviCare Settings → Payment Gateways → Stripe.
Webhook URL: You will see a unique URL generated in the settings. Copy this URL to your clipboard.
Keep this page open, as you will need to paste the “Signing Secret” here later.
Endpoint URL: Paste the URL you copied from your KiviCare settings.
Select events to listen to: Click + Select events and add the following:
payment_intent.succeeded
payment_intent.payment_failed
checkout.session.completed
charge.refunded
Click Add endpoint.
Once the endpoint is created, look for the Signing secret section and click Reveal.
Copy the secret key (it usually starts with whsec_).
Step 3: Finalize KiviCare Settings
Go back to your KiviCare Settings → Payment Gateways → Stripe page.
Webhook Signing Secret: Paste the whsec_ key you copied from Stripe into this field.
Click Save Settings.
3. Key Benefits & Features
Instant Booking Confirmation
Webhooks allow KiviCare to confirm an appointment the exact millisecond a payment is successful. This prevents double-bookings and provides immediate peace of mind to your patients.
Robust Security
By using a Signing Secret, KiviCare performs a cryptographic check on every notification. This ensures that only Stripe can trigger a “Paid” status on your appointments, shielding your clinic from unauthorized status changes.
Automatic Error Handling
If a payment fails or is cancelled at the bank level after the user has left your site, the webhook will notify KiviCare to automatically release the appointment slot and mark the status as “Failed,” keeping your calendar accurate.
4. Supported Payment Events
Event
Action in KiviCare
payment_intent.succeeded
Confirms the appointment and sets payment to Completed.
checkout.session.completed
Finalizes the booking for web-based payments.
payment_intent.payment_failed
Cancels the appointment and marks payment as Failed.
charge.refunded
Updates the transaction record to Refunded.
Troubleshooting
Common Issues and Solutions
Payment Failed
Verify the Secret Key and Publishable Key are correct.
Ensure keys match the selected Mode (Test or Live).
Confirm that your Stripe account is fully activated for live payments.
Currency Not Supported
Ensure the selected currency is supported by Stripe.
Check currency availability in your Stripe account settings.
“Stripe gateway is not properly configured” Error
This error indicates the Secret API Key is missing or invalid.
Re-check the Stripe settings in KiviCare.
Stripe Form Not Loading
Ensure your site is using HTTPS.
Best Practices
Always test payments using Sandbox mode before switching to Live.
Keep your Secret API Key confidential.
Regularly review transactions from the Stripe Dashboard.
