This document explains how to configure, enable, and use the PayPal Payment Gateway in the KiviCare Clinic Management System. It is intended for administrators and site owners who want to accept online payments from patients during appointment booking.
Overview
The PayPal payment gateway allows clinics to securely accept online payments from patients using PayPal. The integration is built using the PayPal REST API, ensuring secure and reliable transaction processing.
With PayPal enabled, patients can complete appointment payments using:
PayPal balance
Credit cards
Debit cards (supported by PayPal)
Prerequisites
Before configuring PayPal in KiviCare, make sure you have the following:
A PayPal Business Account
Access to the PayPal Developer Dashboard
A valid SSL certificate (HTTPS enabled) on your website
PayPal 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 PayPal Gateway
Locate PayPal in the list of available payment gateways.
Toggle the Enable switch (Green).
Click on Manage (or the edit icon) to open PayPal settings.
Step 3: Configure PayPal Settings
Fill in the following fields:
Enable PayPal
Ensure this option is checked to activate PayPal payments.
Mode
Choose the environment:
Sandbox (Test Mode) – For testing transactions
Live – For accepting real payments
Client ID
Enter your PayPal REST API Client ID.
Client Secret
Enter your PayPal REST API Client Secret.
Currency
Select the currency you want to accept payments in (e.g., USD, EUR, INR).
Step 4: Save Settings
Click the Save button to apply and store your PayPal configuration.
How to Obtain PayPal API Credentials
Follow these steps to generate PayPal API credentials:
Log in to the PayPal Developer Dashboard.
Navigate to Apps & Credentials.
Select the environment:
Sandbox for testing
Live for production payments
Click Create App.
Enter an app name (e.g., KiviCare Clinic) and click Create App.
After the app is created, you will see:
Client ID
Secret (click Show to reveal it)
Copy these values and paste them into the KiviCare PayPal settings.
Important: Sandbox credentials will only work in Sandbox mode, and Live credentials will only work in Live mode.
Payment Flow
Patient books an appointment.
Patient selects PayPal as the payment method.
Patient is redirected to PayPal to complete the payment.
After successful payment, the appointment is confirmed in KiviCare.
Payment status is recorded in the system.
PayPal Webhook & Webhook ID Configuration
1. Introduction
The PayPal Webhook integration allows KiviCare to receive automated notifications directly from PayPal whenever a payment is completed, pending, or denied. This ensures your appointment statuses are updated in real-time, even if the patient closes the PayPal tab before returning to your clinic site.
The Webhook ID is used by KiviCare to verify that every notification received is a genuine message from PayPal, ensuring the security and integrity of your booking data.
2. Configuration Guide
Step 1: KiviCare Setup
Log in to your WordPress Admin Dashboard.
Navigate to KiviCare Settings → Payment Gateways → PayPal.
Webhook URL: Locate the unique URL generated in the settings. Copy this URL to your clipboard.
Keep this page open; you will need to paste the “Webhook ID” here in the final step.
Navigate to Apps & Credentials and select the App you are using for KiviCare (ensure you select the correct environment: Sandbox or Live).
Scroll down to the Webhooks section and click Add Webhook.
Webhook URL: Paste the URL you copied from KiviCare.
Event types: Select the following events from the list:
Payment sale completed
Payment order completed
Payment capture completed
Checkout order approved
Payment sale denied
Payment sale refunded
Click Save.
Once saved, PayPal will generate a Webhook ID. Copy this ID (it usually looks like WH-XXXXXXXXXXXXXXXXX).
Step 3: Finalize KiviCare Settings
Go back to your KiviCare Settings → Payment Gateways → PayPal.
Webhook ID: Paste the ID you copied from the PayPal dashboard into this field.
Click Save Settings.
3. Key Benefits & Features
Guaranteed Synchronization
Webhooks act as a backup for the standard checkout process. If a patient’s internet drops after paying but before the redirect finishes, the webhook ensures the appointment is still confirmed in your clinic database.
Multi-Event Support
KiviCare doesn’t just listen for “Success.” It also tracks:
Pending Payments: Keeps the slot held while the payment clears.
Denied Payments: Automatically cancels the appointment if the payment is rejected by the bank.
Refunds: Marks the internal record as refunded if you issue a refund through PayPal.
Verified Security
By using the Webhook ID, KiviCare performs a verification check against PayPal’s official servers for every notification received. This prevents “spoofing” (where someone tries to trick your site into thinking a payment was made without actually paying).
4. Supported Status Mapping
PayPal Event
KiviCare Action
SALE.COMPLETED
Confirms the appointment and marks as Paid.
SALE.PENDING
Sets appointment to Pending (Waiting for funds).
SALE.DENIED
Sets appointment to Cancelled or Failed.
Troubleshooting
Common Issues and Solutions
Payment Failed
Verify that the Client ID and Client Secret are correct.
Ensure the selected Mode matches the credentials (Sandbox or Live).
Confirm that your PayPal account is verified and active.
Currency Not Supported
Make sure the selected currency is supported by PayPal.
Check PayPal documentation for supported currencies.
SSL / TLS Error
PayPal requires HTTPS.
Ensure your website has a valid SSL certificate installed and active.
PayPal Option Not Visible
Confirm PayPal is enabled in KiviCare > Settings > Payment Settings.
