> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PayFast

> Configure PayFast for South Africa, including the passphrase that signs every payment and notification.

# Collect payments with PayFast

`PAYFAST` posts a signed payment request to PayFast's hosted page. The payer
completes the payment there, and PayFast confirms it with an **ITN** (Instant
Transaction Notification) that is signature-checked before anything is credited.

Available to ISPs in **South Africa (ZA)**, alongside Paystack, PayPal, and DPO.

## Before you start

1. Complete PayFast merchant onboarding in an account owned by the ISP.
2. In the PayFast dashboard open **Settings → Integration** and collect the
   **merchant ID** and **merchant key**.
3. Set a **passphrase** in the same place, and be ready to enter the identical
   value here — see the warning below.
4. Plan the walled garden: the payer's browser must reach
   `www.payfast.co.za`, so a Hotspot subscriber who is not yet online cannot
   pay unless PayFast is reachable pre-authentication.

## Configure the gateway

<Steps>
  <Step title="Open Settings → Payments → PayFast">
    Select PayFast from the payment marketplace.
  </Step>

  <Step title="Enter the merchant ID and merchant key">
    Both are required, and both come from PayFast dashboard → Settings →
    Integration.
  </Step>

  <Step title="Enter the passphrase">
    **Passphrase** is optional in the form — PayFast allows unsigned merchants —
    but it is strongly recommended. It must be **character-for-character
    identical** to the passphrase saved in your PayFast dashboard.
  </Step>

  <Step title="Register the ITN, return, and cancel URLs">
    See [Callback URLs](#callback-urls) below.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal on an unauthenticated device and
    confirm the payment reaches the ledger.
  </Step>
</Steps>

<Warning>
  A passphrase that differs from PayFast's — including a stray space — makes
  every signature mismatch. Payments are then rejected, or notifications are
  discarded, in a way that looks like an intermittent gateway fault rather than
  a configuration error. Set it on both sides at the same time, or leave it
  blank on both.
</Warning>

## Credentials

| Field        | Required | Notes                                                                               |
| ------------ | -------- | ----------------------------------------------------------------------------------- |
| Merchant ID  | Yes      | PayFast dashboard → Settings → Integration.                                         |
| Merchant key | Yes      | Same place.                                                                         |
| Passphrase   | No       | Secret. Signs payment data and validates notifications. Must match PayFast exactly. |

The merchant ID and key gate the switch; the passphrase does not, which is
exactly why a mismatch is easy to ship.

## Callback URLs

| Name             | Path                                              |
| ---------------- | ------------------------------------------------- |
| Notify URL (ITN) | `https://<your-host>/api/payments/payfast/notify` |
| Return URL       | `https://<your-host>/tenant/payfast/return`       |
| Cancel URL       | `https://<your-host>/tenant/payfast/cancel`       |

Set all three in the PayFast dashboard, and confirm the notify URL is publicly
reachable — it is what completes a payment.

## What the payer must provide

Whatever PayFast's page asks for — card, instant EFT, or another method enabled
on your account. The amount, reference, and signature are fixed before the payer
arrives.

<Note>
  PayFast is always live here. There is no sandbox switch on this form, so test
  with a small real amount rather than with sandbox credentials.
</Note>

## How a payment completes

<Steps>
  <Step title="Signed redirect">
    Centipid Billing builds the payment fields in PayFast's canonical order,
    signs them with your passphrase, and redirects the payer to PayFast with the
    signature attached.
  </Step>

  <Step title="Payment">
    The payer completes the payment on PayFast's page.
  </Step>

  <Step title="Confirmation">
    PayFast posts the ITN. Its signature is recomputed with your passphrase and
    compared; only a matching notification records a payment and applies the
    package.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                                                                   | What it means                                                                                     | What to do                                                                                                                            |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| *"Payment failed: PayFast is not fully configured. Please add your merchant ID and key."* | One of the two required fields is missing.                                                        | Complete both in Settings → Payments.                                                                                                 |
| PayFast's page rejects the request as an invalid signature                                | The passphrase here does not match the one in the PayFast dashboard.                              | Re-enter it on both sides, watching for trailing spaces.                                                                              |
| Payments complete at PayFast, ledger stays empty                                          | ITNs are being discarded — a passphrase mismatch, or a notify URL that is not publicly reachable. | Check both, then re-test with a small payment.                                                                                        |
| The payment page never loads on a Hotspot device                                          | The walled garden does not allow PayFast.                                                         | Allow `www.payfast.co.za` pre-authentication — see [Captive device cannot reach checkout](/billing/payment-gateways/troubleshooting). |

For every gateway's fields in one place, see the
[credential reference](/billing/payment-gateways/credentials-reference).