Build a Telemedicine Consultation Payment Flow
Build a telemedicine payment flow by requiring patients to pay the consultation fee via Paystack before the video call link is revealed, confirming payment via the charge.success webhook, and disbursing the doctor's share via Paystack Transfers after the consultation is completed and marked by the doctor. Use Paystack Subaccounts for automatic per-doctor settlement if you have many doctors.
Consultation Booking and Prepayment
Tables: doctors (name, specialty, consultation_fee, paystack_subaccount_code, paystack_recipient_code), consultations (patient_id, doctor_id, scheduled_at, duration_mins, status, video_link, paystack_ref, paid_at).
async function bookConsultation(patientEmail, patientId, doctorId, scheduledAt) {
var doctor = await db.doctors.findById(doctorId);
var reference = 'TELE-' + Date.now();
var consultation = await db.consultations.create({
patient_id: patientId,
doctor_id: doctorId,
scheduled_at: scheduledAt,
status: 'pending_payment',
paystack_ref: reference,
});
// Payment required before video link is revealed
var res = await fetch('https://api.paystack.co/transaction/initialize', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
email: patientEmail,
amount: doctor.consultation_fee,
currency: 'NGN',
reference,
subaccount: doctor.paystack_subaccount_code, // doctor gets their share automatically
bearer: 'subaccount', // platform fees deducted from doctor's share
metadata: { consultation_id: consultation.id, patient_id: patientId, doctor_id: doctorId },
}),
});
return { consultation, authorizationUrl: (await res.json()).data.authorization_url };
}
// Webhook: payment confirmed — generate and reveal video link
if (event.event === 'charge.success') {
var meta = event.data.metadata;
if (!meta.consultation_id) return res.sendStatus(200);
var videoLink = await createVideoRoom(meta.consultation_id); // e.g., Daily.co or Jitsi
await db.consultations.update(meta.consultation_id, {
status: 'confirmed',
video_link: videoLink,
paid_at: new Date(),
});
await sendConsultationConfirmation(meta.patient_id, meta.doctor_id, videoLink);
}Consultation Completion and Refund Handling
// Doctor marks consultation complete
async function completeConsultation(doctorId, consultationId, notes) {
var consultation = await db.consultations.findById(consultationId);
if (consultation.doctor_id !== doctorId) throw new Error('Not your consultation');
if (consultation.status !== 'confirmed') throw new Error('Consultation not confirmed');
await db.consultations.update(consultationId, {
status: 'completed',
doctor_notes: notes,
completed_at: new Date(),
});
// If not using subaccounts, manually pay doctor via Transfer
var doctor = await db.doctors.findById(doctorId);
if (!doctor.paystack_subaccount_code && doctor.paystack_recipient_code) {
var platformFee = Math.floor(consultation.fee * 0.15); // 15% platform fee
var doctorPayout = consultation.fee - platformFee;
await fetch('https://api.paystack.co/transfer', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ source: 'balance', amount: doctorPayout, recipient: doctor.paystack_recipient_code, reason: 'Consultation payout' }),
});
}
}
// Doctor cancels — refund patient in full
async function cancelByDoctor(doctorId, consultationId) {
var consultation = await db.consultations.findById(consultationId);
if (consultation.doctor_id !== doctorId) throw new Error('Not your consultation');
await fetch('https://api.paystack.co/refund', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ transaction: consultation.paystack_ref }),
});
await db.consultations.update(consultationId, { status: 'cancelled_by_doctor' });
await notifyPatient(consultation.patient_id, 'Your consultation was cancelled. Full refund issued.');
}Learn More
See build a veterinary clinic booking and payment system for a related booking + deposit pattern applied to in-person appointments.
Key Takeaways
- ✓Require payment before the video call link is shown — this eliminates no-shows.
- ✓Issue the consultation link only in the charge.success webhook, never before.
- ✓Doctors on the platform can receive payouts via Paystack Transfers to their bank account.
- ✓For multi-doctor platforms, Paystack Subaccounts automate per-doctor revenue splitting.
- ✓Refund the patient in full if the doctor cancels — use the Paystack Refund API with the original reference.
Frequently Asked Questions
- How do I handle patients who do not show up for the video call?
- Patient no-shows should not result in a refund — the doctor's time was reserved. Define a no-show policy: if the patient does not join within 10 minutes of the start time, the consultation is marked "no_show" and no refund is issued. The doctor still receives their payout. Communicate this policy clearly at booking.
- Should I use Paystack Subaccounts or manual Transfers for doctor payouts?
- Subaccounts are cleaner at scale — the split happens automatically at payment time and you never need to manually transfer each doctor's earnings. Use Subaccounts if you have 5+ doctors. Use manual Transfers (charge to your account, pay doctors periodically) if you are a solo clinic or have a complex per-consultation fee structure that does not map to a fixed percentage.
- What video platform should I integrate with?
- Daily.co (REST API to create rooms, easy to embed), Twilio Video, or Whereby work well for telemedicine. For simpler implementations, generate a unique Jitsi Meet room URL (no API needed). Reveal the link only after payment. For privacy-sensitive consultations, choose a platform with end-to-end encryption and no recording by default.
Ready to build real-world apps?
Join the McTaba Labs full-stack marathon (4 months full-time · 6 months part-time). Learn M-Pesa, USSD, and WhatsApp engineering while shipping 8 production apps.
Apply to the McTaba Marathon