Skip to content

PayFast

Applies to: Owner and Administrator (school set-up); students (paying); developers and DriveFlow operations (server set-up). Last reviewed: 2026-11-18.

PayFast is the only working payment gateway in DriveFlow. It is used in two separate ways, with two separate merchant accounts:

  • Part A - schools paying DriveFlow (plans, add-ons, SMS bundles), into DriveFlow's account.
  • Part B - students paying a school (invoices, from the student portal), into the school's own account.

Part A - Schools paying DriveFlow

What a school has to set up

Nothing. The school does not need a PayFast account to pay DriveFlow. The person paying only needs a way to pay on PayFast's page (card, EFT or another method PayFast offers).

The flow

sequenceDiagram
    actor Owner
    participant DF as DriveFlow
    participant PF as PayFast
    Owner->>DF: 1. Clicks a payment button (Continue to Payment / Activate / Pay next month / Buy bundle)
    DF->>DF: 2. Creates a payment record: status Pending, amount, reference DF-date time-random
    DF->>PF: 3. Builds a signed PayFast link and sends the browser to PayFast
    Owner->>PF: 4. Pays on PayFast
    par Browser return
        PF->>Owner: 5a. Sends the browser back to the Subscription payment page (not proof of payment)
        Owner->>DF: 6. The page keeps asking DriveFlow until the payment shows as confirmed
    and Server notification
        PF->>DF: 5b. Calls DriveFlow's server (ITN), checked, then applied
        DF->>DF: Payment Successful, plan / add-on / credits activated, invoice created and emailed
    end

The payment reference has the form DF-<date time>-<random>.

Important

The browser coming back from PayFast is never treated as proof of payment. Only PayFast's server-to-server notification activates anything.

What is sent to PayFast

DriveFlow's merchant ID and key, the return, cancel and notify addresses, the school's email address, DriveFlow's payment reference (as m_payment_id), the amount with two decimals, the item name (for example "Professional - Monthly") and a signature. The name fields are fixed as "DriveFlow" / "Subscription".

It is a single, once-off payment. No recurring-billing fields are sent.

For an add-on payment the return and cancel addresses carry the payment reference (?addon=…), so the result page waits for that particular payment.

The notification (ITN) and its checks

PayFast's notification is anonymous (PayFast is not a signed-in user), so nothing is trusted until every check passes. In order:

# Check If it fails
1 The request is a form post Rejected (400)
2 merchant_id equals DriveFlow's merchant ID Rejected (400), logged "Invalid PayFast merchant ID."
3 A reference and a PayFast payment ID are present Rejected (400)
4 Signature: a hash over every posted field, in the order PayFast posted them, up to the signature field, with DriveFlow's passphrase appended; compared in constant time Rejected (400), logged "Invalid PayFast signature"
5 payment_status is COMPLETE Accepted (200) but nothing is changed; the status is only logged
6 Server confirmation: DriveFlow posts the notification back to PayFast's validation address; PayFast must answer VALID Rejected (400). PayFast will retry, so a temporary network problem does not lose the payment
7 The gross amount is a valid number Rejected (400)
8 The payment reference exists Rejected (400): "Subscription payment was not found."
9 Amount: the gross amount equals the amount DriveFlow recorded for that reference Rejected (400): "Payment amount does not match the subscription payment." Nothing is activated

The raw request body is read rather than the parsed form, because the signature depends on the exact order of the fields.

Idempotency: one payment is applied once

PayFast repeats a notification until it receives a success answer, and two copies can arrive at the same time.

How DriveFlow applies each payment exactly once
  • If the payment is already Successful, DriveFlow answers success and does nothing.
  • Otherwise it "claims" the payment with a single conditional database update (set to Successful only if it is not already Successful). Exactly one delivery can win; any other sees that nothing was updated and stops.
  • The claim, the activation, the invoice and any sales commission are saved in one database transaction. If any part fails, the whole thing is rolled back, the payment stays Pending, PayFast receives an error and tries again.
  • An invoice is only created if none exists for that payment reference.

The automated tests cover a replayed notification, concurrent deliveries, a bad signature, a foreign merchant ID and a mismatched amount.

What is activated

What was bought What the confirmed payment does
A plan Sets the subscription to the paid plan and billing cycle, status Active, clears any cancellation, sets the new end date. Same plan and cycle while still running: the period is added on from the current end date. Anything else: the period starts now.
A monthly add-on Adds one month to the add-on's paid-until date (from the current date if still paid up, otherwise from now), clears a cancellation, records the setup fee as paid if it was included.
Leads and WhatsApp together Does the above for both add-ons from the one payment.
An SMS bundle Adds the bundle's credits to the balance; records the setup fee as paid if it was included.

Then, for all of them:

  • the PayFast transaction ID, the fee PayFast kept and the completion time are stored on the payment,
  • a paid invoice is created,
  • the school's cached access is cleared so the change is visible at once,
  • the invoice is emailed to the organisation. A failed email never undoes the activation.

What the school sees

See Subscription management for the screens: "Confirming your payment...", "Payment received", "Payment cancelled", and the message shown when confirmation takes longer than about 30 seconds.

Server settings (DriveFlow operations)

DriveFlow's own PayFast account is configured on the server by DriveFlow operations. Values are never shown in the application. The individual settings are covered in the internal technical documentation.

If DriveFlow's merchant ID or key is missing, every checkout fails with "PayFast is not configured."

The API must be reachable from the internet at the notify addresses, or payments will never be confirmed.


Part B - Students paying a school

A school can let its students pay invoices from the student portal. The money goes straight into the school's own PayFast account.

Requirements

What you need

  • A plan that includes Invoices and Payments (every plan does) and, for the student to reach the portal at all, the Student Portal (Professional and above, or the trial).
  • The school's own PayFast merchant account.
  • Online payments switched on under Settings > Payments.

Set up online payments (school)

Viewing needs Settings.View; changing needs Settings.Manage. Users who can only view see "You can view these settings but not change them."

  1. In PayFast, open Settings > Integration and note your Merchant ID and Merchant key. If you have set a passphrase there, note it too.
  2. In DriveFlow go to Settings > Payments.
  3. Scroll to Online Payments (PayFast).
  4. Fill in:

    Field Required Meaning
    Merchant ID Yes, to switch on Your PayFast merchant ID. Digits only, for example 10000100.
    Merchant key Yes, to switch on Your PayFast merchant key. It is stored securely and never shown again. Once saved, the field says "Saved - leave blank to keep"; type a new key only to replace it.
    Passphrase Only if you set one in PayFast Must match the passphrase in PayFast exactly. Stored securely. Tick Remove the saved passphrase to delete it.
    Allow part payments No Off: students pay the whole balance of an invoice. On: they choose how much.
    Test mode (PayFast sandbox) No On: payments go to PayFast's sandbox using your sandbox details, and no real money moves.
    Switch at the top (On / Off) - Turns online payments on for students.
  5. Click Save online payments.

You see "Online payments saved. Students can now pay from the portal." (or "Online payments saved." when it is off).

Screenshot to be added

Screen: Settings > Payments. Should show: Online Payments (PayFast) card with Merchant ID, Merchant key, Passphrase and the switches.

Test mode

With test mode and online payments both on, a warning is shown: "Test mode is on: students won't be charged, and nothing is paid into your account. Switch it off before students start paying for real."

Messages when saving

Message Why
The PayFast merchant ID is a number, e.g. 10000100. You'll find it under Settings > Integration in PayFast. The merchant ID contains something other than digits.
One of the PayFast details is too long. Please check you copied the right values. Merchant ID over 50 characters, or key or passphrase over 100.
Enter your PayFast merchant ID and merchant key before switching online payments on. Switched on without both values.

How a student pays

  1. The student signs in to the portal and opens their invoices.
  2. On an invoice with a balance, they choose to pay. The dialog Pay invoice number shows "Balance owing".
  3. If part payments are allowed, they can change Amount to pay ("Pay the full balance or part of it (at least R 5.00).").
  4. They click Pay R … and are taken to PayFast. ("You'll be taken to PayFast to pay securely by card, EFT or another method, then brought back here. Your driving school receives the payment directly.")
  5. After paying they return to the portal's Payment page, which waits for PayFast's confirmation (it checks every 3 seconds for about a minute).
What the student sees When
Payment received - "Thank you. R … was paid towards invoice …" and "Your receipt has been emailed to you." PayFast has confirmed.
Confirming your payment… - "We're waiting for PayFast to confirm it. This usually takes a few seconds." Still waiting.
"PayFast hasn't confirmed this payment yet. That can take a few minutes, for example with EFT. It will show on your invoices once confirmed, and you'll get a receipt by email." Not confirmed after about a minute.
Payment not completed - "Nothing was paid. You can try again whenever you're ready." The student cancelled at PayFast, or the payment failed.

Rules applied when a student starts a payment

Rule Message
Online payments must be on and set up, and the plan must include payments Online payments aren't available at your driving school. Please contact them to pay.
The invoice must belong to the student Invoice not found.
The invoice must not be a draft, cancelled, a credit or already paid This invoice doesn't need paying.
The amount cannot exceed the balance, less any payment started in the last hour that is still unfinished You can pay at most amount on this invoice.
If an unfinished payment already covers the balance A payment for this invoice is already in progress. If you didn't finish it, please try again in an hour.
PayFast's minimum is R 5 The smallest amount you can pay online is 5.00. / This balance is too small to pay online. Please contact your driving school.

The one-hour rule stops an invoice from being paid twice from two browser tabs. If the student returns from PayFast having cancelled, the unfinished payment is released at once so they can try again.

The notification and its checks

The student-payment notification is also anonymous. The checks mirror Part A, but against the school's details:

  1. A reference and a PayFast payment ID are present.
  2. The reference belongs to a known PayFast transaction (found across all schools by its reference, which starts with DFS-).
  3. The school has PayFast details saved (it is still honoured if the school has since switched online payments off).
  4. merchant_id equals the school's merchant ID.
  5. The signature is valid using the school's passphrase.
  6. payment_status is COMPLETE; anything else is acknowledged and ignored.
  7. PayFast's server confirms the notification (sandbox or live according to the school's test mode setting).
  8. The gross amount matches the amount of the transaction, to within one cent.

Then the transaction is claimed with a single conditional update, so that only one delivery records the payment. A transaction the student had marked as cancelled can still be completed this way, which covers slow EFT payments. If an earlier attempt marked the transaction successful but failed before recording the payment, the next notification finishes the job.

Recording the payment creates a normal payment against the invoice, updates the invoice balance and status, and emails the student a receipt. From then on it appears under Payments like any other payment. How payments, receipts and invoice statuses work is covered in the payments documentation.

Security notes

  • The school's merchant key and passphrase are stored securely and are never returned to the browser; the page only knows whether one is saved.
  • If saved PayFast details can ever no longer be read after server maintenance, online payments become unavailable without warning until the school enters them again.

Troubleshooting

Symptom Likely cause
"PayFast is not configured." when paying DriveFlow DriveFlow's merchant details are missing on the server. Contact DriveFlow.
Paid on PayFast but DriveFlow still shows "Confirming your payment..." after several minutes PayFast's notification has not reached DriveFlow, or failed a check. PayFast retries. The payment stays Pending in Payment History until it succeeds. Contact DriveFlow with the reference.
Student sees "Online payments aren't available at your driving school." Online payments are off, the merchant ID or key is missing, or the saved details can no longer be read. Re-enter them under Settings > Payments.
Student payments never confirm The passphrase in DriveFlow does not match the one in PayFast (signature check fails), the merchant ID is wrong, or test mode does not match the kind of PayFast account used.
PayFast rejects the payment page with a signature error The passphrase saved in DriveFlow differs from the one on the PayFast account.

Limitations and notes

  • No recurring billing. Neither use sets up a PayFast subscription or stores a card.
  • No refunds through PayFast from DriveFlow. PayFast refunds are done in the PayFast dashboard. See the note in Payment gateways.
  • No test button. There is no "test connection" for a school's PayFast details. Use test mode with sandbox details and a small invoice to check the set-up.
  • Fees. PayFast's fee on a subscription payment is stored for DriveFlow's commission calculations. The fee on a student payment is not recorded; the school sees it in PayFast.
  • A notification with a status other than COMPLETE (for example a failed or cancelled payment) does not update the payment record, so such payments remain Pending in DriveFlow.
  • Only one PayFast account can be configured per school; it is not per branch.