Step 4 – Confirm Payment is Successful

This Instant Transaction Notification (ITN) tells you whether payment was completed or cancelled.

4.1. Set up your notification page

Respond with HTTP 200 OK immediately on receiving the ITN.
If you don’t, Payfast retries immediately, then after 10 minutes, then exponentially longer.
Testing locally? Use a public tunnel like NGROK or Expose to make your local server accessible online.

Example Notification Page:

<?php
// Notify Payfast that this page is reachable by triggering a header response
header( 'HTTP/1.0 200 OK' );
flush();

define( 'SANDBOX_MODE', true );
$pfHost = SANDBOX_MODE ? 'sandbox.payfast.co.za' : 'www.payfast.co.za';
// Posted variables from ITN
$pfData = $_POST;

// Strip any slashes in data
foreach( $pfData as $key => $val ) {
    $pfData[$key] = stripslashes( $val );
}

// Convert posted variables to a string
foreach( $pfData as $key => $val ) {
    if( $key !== 'signature' ) {
        $pfParamString .= $key .'='. urlencode( $val ) .'&';
    } else {
        break;
    }
}

$pfParamString = substr( $pfParamString, 0, -1 );

const axios = require("axios");
const crypto = require("crypto");
const dns = require('dns');

const testingMode = true;
const pfHost = testingMode ? "sandbox.payfast.co.za" : "www.payfast.co.za";

const pfData = JSON.parse(JSON.stringify(req.body));

let pfParamString = "";
for (let key in pfData) {
  if(pfData.hasOwnProperty(key) && key !== "signature"){
    pfParamString +=`${key}=${encodeURIComponent(pfData[key].trim()).replace(/%20/g, "+")}&`;
  }
}

// Remove last ampersand
pfParamString = pfParamString.slice(0, -1);

import requests
import hashlib
import urllib.parse
import socket
from werkzeug.urls import url_parse
from flask import request

SANDBOX_MODE = True

pfHost = 'sandbox.payfast.co.za' if SANDBOX_MODE else 'www.payfast.co.za'

# Get posted variables from ITN and convert to a string
pfData = {}
postData = request.get_data().decode().split('&')
for i in range(0,len(postData)):
    splitData = postData[i].split('=')
    pfData[splitData[0]] = splitData[1]

pfParamString = ""
for key in pfData:
# Get all the data from Payfast and prepare parameter string
    if key != 'signature':
        pfParamString += key + "=" + urllib.parse.quote_plus(pfData[key].replace("+", " ")) + "&"
# After looping through, cut the last & or append your passphrase
# payload += "passphrase=SecretPassphrase123"
pfParamString = pfParamString[:-1]

4.2. ITN parameters you’ll receive

Transaction Details

Parameter	Type	Required	Description
`m_payment_id`	string (100)	No	Your own payment ID
`pf_payment_id`	integer	Yes	Payfast transaction ID
`payment_status`	string	Yes	`COMPLETE` (payment done) or `CANCELLED` (subscription cancelled)
`item_name`	string (100)	Yes	Item name or order number
`item_description`	string (255)	No	Item or order description
`amount_gross`	decimal	No	Total paid (ZAR)
`amount_fee`	decimal	No	Payfast fees deducted
`amount_net`	decimal	No	Amount credited (ZAR)

Custom Fields

custom_int1 … custom_int5 (integer, optional)
custom_str1 … custom_str5 (string, optional)

Customer Details

name_first (string, optional)
name_last (string, optional)
email_address (string, optional)

Merchant Details

merchant_id (integer, required)

Recurring Billing

token (string, required)
billing_date (YYYY-MM-DD, optional)

Security

signature (MD5 hash, optional) – signature of all URL-encoded POST vars.

4.3. Security Checks (Required)

You must run 4 checks before accepting the payment.

1. Verify Signature

Make sure Payfast’s signature matches what you calculate.

function pfValidSignature($pfData, $pfParamString, $pfPassphrase = null) {
    $tempParamString = $pfPassphrase
        ? $pfParamString.'&passphrase='.urlencode($pfPassphrase)
        : $pfParamString;

    $signature = md5($tempParamString);
    return ($pfData['signature'] === $signature);
}

const pfValidSignature = (pfData, pfParamString, pfPassphrase = null ) => {
  // Calculate security signature
  let tempParamString = '';
  if (pfPassphrase !== null) {
    pfParamString +=`&passphrase=${encodeURIComponent(pfPassphrase.trim()).replace(/%20/g, "+")}`;
  }

  const signature = crypto.createHash("md5").update(pfParamString).digest("hex");
  return pfData['signature'] === signature;
};

def pfValidSignature(pfData, pfParamString):
  # Generate our signature from Payfast parameters
  signature = hashlib.md5(pfParamString.encode()).hexdigest()
  return (pfData.get('signature') == signature)

2. Check IP address is from Payfast

Valid domains:

www.payfast.co.za
sandbox.payfast.co.za
w1w.payfast.co.za
w2w.payfast.co.za

Example:

function pfValidIP() {
    $validHosts = ['www.payfast.co.za', 'sandbox.payfast.co.za', 'w1w.payfast.co.za', 'w2w.payfast.co.za'];
    $validIps = [];

    foreach ($validHosts as $host) {
        $ips = gethostbynamel($host);
        if ($ips) $validIps = array_merge($validIps, $ips);
    }

    $validIps = array_unique($validIps);
    $referrerIp = gethostbyname(parse_url($_SERVER['HTTP_REFERER'])['host']);

    return in_array($referrerIp, $validIps, true);
}

async function ipLookup(domain){
  return new Promise((resolve, reject) => {
    dns.lookup(domain, {all: true}, (err, address, family) => {
      if(err) {
        reject(err)
      } else {
        const addressIps = address.map(function (item) {
         return item.address;
        });
        resolve(addressIps);
      }
    });
  });
}

const pfValidIP = async (req) => {
  const validHosts = [
    'www.payfast.co.za',
    'sandbox.payfast.co.za',
    'w1w.payfast.co.za',
    'w2w.payfast.co.za'
  ];

  let validIps = [];
  const pfIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;

  try{
    for(let key in validHosts) {
      const ips = await ipLookup(validHosts[key]);
      validIps = [...validIps, ...ips];
    }
  } catch(err) {
    console.error(err);
  }

  const uniqueIps = [...new Set(validIps)];

  if (uniqueIps.includes(pfIp)) {
    return true;
  }
  return false;
};

def pfValidIP():
    valid_hosts = [
    'www.payfast.co.za',
    'sandbox.payfast.co.za',
    'w1w.payfast.co.za',
    'w2w.payfast.co.za',
    ]
    valid_ips = []

    for item in valid_hosts:
        ips = socket.gethostbyname_ex(item)
        if ips:
            for ip in ips:
                if ip:
                    valid_ips.append(ip)
    # Remove duplicates from array
    clean_valid_ips = []
    for item in valid_ips:
        # Iterate through each variable to create one list
        if isinstance(item, list):
            for prop in item:
                if prop not in clean_valid_ips:
                    clean_valid_ips.append(prop)
        else:
            if item not in clean_valid_ips:
                clean_valid_ips.append(item)

    # Security Step 3, check if referrer is valid
    if url_parse(request.headers.get("Referer")).host not in clean_valid_ips:
        return False
    else:
        return True

3. Compare Payment Data

Ensure amount_gross matches what you expected.

function pfValidPaymentData($cartTotal, $pfData) {
    return !(abs((float)$cartTotal - (float)$pfData['amount_gross']) > 0.01);
}

const pfValidPaymentData = ( cartTotal, pfData ) => {
    return Math.abs(parseFloat(cartTotal) - parseFloat(pfData['amount_gross'])) <= 0.01;
};

def pfValidPaymentData(cartTotal, pfData):
    return not (abs(float(cartTotal)) - float(pfData.get('amount_gross'))) > 0.01

4. Confirm with Payfast Server

Send the exact POST data back to Payfast for validation.

function pfValidServerConfirmation($pfParamString, $pfHost = 'sandbox.payfast.co.za') {
    if (in_array('curl', get_loaded_extensions(), true)) {
        $url = 'https://' . $pfHost . '/eng/query/validate';

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $pfParamString);

        $response = curl_exec($ch);
        curl_close($ch);

        return ($response === 'VALID');
    }
    return false;
}

const https = require('https');
const querystring = require('querystring');

function pfValidServerConfirmation(pfParamString, pfHost = 'sandbox.payfast.co.za') {
    return new Promise((resolve, reject) => {
        const postData = pfParamString;

        const options = {
            hostname: pfHost,
            path: '/eng/query/validate',
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

        const req = https.request(options, (res) => {
            let data = '';
            res.on('data', chunk => data += chunk);
            res.on('end', () => resolve(data === 'VALID'));
        });

        req.on('error', reject);
        req.write(postData);
        req.end();
    });
}

import requests

def pf_valid_server_confirmation(pf_param_string, pf_host='sandbox.payfast.co.za'):
    url = f'https://{pf_host}/eng/query/validate'
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
    }

    response = requests.post(url, data=pf_param_string, headers=headers, verify=True)
    return response.text == 'VALID'

CURL Options

Option	Description
`CURLOPT_RETURNTRANSFER`	Set to `TRUE` to return the transfer as a string of the return value of `curl_exec()` instead of outputting it directly.
`CURLOPT_HEADER`	Set to `FALSE` to exclude the header in the output.
`CURLOPT_SSL_VERIFYHOST`	Set to `2` to check the existence of a common name in the SSL peer certificate, and to also verify that it matches the hostname provided.
`CURLOPT_SSL_VERIFYPEER`	Determines whether cURL verifies the authenticity of the peer’s certificate. The default value is `1`.
`CURLOPT_URL`	Set to the Payfast query validation URL, e.g. `https://www.payfast.co.za/eng/query/validate`. This can also be set when initializing a session with `curl_init()`.
`CURLOPT_POST`	Set to `TRUE` to do a regular HTTP POST. This POST is the normal `application/x-www-form-urlencoded` kind, most commonly used by HTML forms.
`CURLOPT_POSTFIELDS`	The full data to post via HTTP to Payfast. This parameter is passed as a URL-encoded string, such as: `m_payment_id=01&pf_payment_id=01234...`

4.4. Bringing it together

$check1 = pfValidSignature($pfData, $pfParamString);
$check2 = pfValidIP();
$check3 = pfValidPaymentData($cartTotal, $pfData);
$check4 = pfValidServerConfirmation($pfParamString, $pfHost);

if ($check1 && $check2 && $check3 && $check4) {
    // ✅ All checks passed – Payment successful
} else {
    // ❌ One or more checks failed – Log & review manually
}

const check1 = pfValidSignature(pfData, pfParamString, passPhrase);
const check2 = pfValidIP(req);
const check3 = pfValidPaymentData( cartTotal, pfData );
const check4 = pfValidServerConfirmation(pfHost, pfParamString);

if(check1 && check2 && check3 && check4) {
    // All checks have passed, the payment is successful
} else {
    // Some checks have failed, check payment manually and log for investigation
}

check1 = pfValidSignature(pfData, pfParamString)
check2 = pfValidIP()
check3 = pfValidPaymentData(cartTotal, pfData)
check4 = pfValidServerConfirmation(pfParamString, pfHost);

if(check1 and check2 and check3 and check4):
    # All checks have passed, the payment is successful
else:
    # Some checks have failed, check payment manually and log for investigation

Payfast Payment Confirmation Flow

flowchart TD
    A[Receive ITN from Payfast at notify_url] --> B[Send HTTP 200 OK response immediately]
    B --> C[Run Security Checks]

    C --> C1[Verify signature matches]
    C --> C2[Check IP address belongs to Payfast]
    C --> C3[Compare amount_gross to expected total]
    C --> C4[Confirm data with Payfast server]

    C1 --> D{All checks pass?}
    C2 --> D
    C3 --> D
    C4 --> D

    D -- Yes --> E[Mark payment as successful]
    D -- No --> F[Log and flag for manual review]
    E --> G[Update order status & fulfil order]
    F --> H[Stop processing & investigate]

Quick test in Sandbox (no code)

Use Payfast’s Sandbox to generate a test form and run a full payment flow with your sandbox merchant.

Open: https://sandbox.payfast.co.za/integration-test

Before you start

Sandbox merchant_id / merchant_key (and passphrase if enabled).
return_url, cancel_url, and notify_url that are reachable from the internet.
Your app/server is ready to receive ITNs (webhooks) (returns HTTP 200 OK).
(Optional) Split payments / Subscriptions are enabled on your account if you plan to test them.

Steps

Go to Integration Test and choose Full form (or Basic form for required fields only).You can also tick Include Split payments and/or Include Subscriptions.
Click Generate testing form.
A Sandbox form is generated. Review or edit the fields (amount, item_name, URLs, etc.) and submit.
Complete the payment on the Payfast sandbox checkout.
Verify the results:
- You’re redirected to your return_url (success) or cancel_url (cancelled).
- Your server receives an ITN at notify_url and responds 200 OK.
- The transaction appears under Sandbox → Transactions in your portal.

Troubleshooting

Signature mismatch: Build the payload string in the exact order and encoding your code uses (spaces as + vs %20) and, if you use a passphrase, append it last. You can validate strings with the Signature troubleshooter at Integration Tools.
ITN not received: Ensure notify_url is publicly reachable (no VPN/intranet), returns 200 OK, and doesn’t redirect. Log the raw POST body.
Feature errors: If you ticked Split payments or Subscriptions, confirm the feature is enabled on your sandbox merchant and any required IDs/fields are present.

Tip: Keep this as a final “smoke test” after you’ve verified your Security Signature.