Onsite Payments Integration Overview

Integrating Onsite Payments is a simple two-step process:

Step 1: Post payment details and get a unique payment identifier (UUID)

Send the transaction and customer details to PayFast to generate a payment UUID. This identifier is required to initiate the PayFast Onsite payment modal.

Endpoints:

Environment	URL
Live	`https://www.payfast.co.za/onsite/process`

📘
Note: PayFast Onsite payments do not provide a dedicated sandbox endpoint. Testing should be performed using a test merchant account configured in sandbox mode.

POST Data:

You’ll send the required payment data described in the [Quickstart guide]. In addition, Onsite Payments requires:

Field	Type	Required Condition	Description
`signature`	string	Required	Hash of posted data to ensure data integrity
`email_address`	string (max 100)	Required unless mobile registration is allowed	Customer’s email address
`cell_number`	string (max 100)	Required if `email_address` is not provided	Customer’s valid cell number (used as username for login)

If no return_url is provided, the payment modal simply closes after payment completion without redirecting.

Sample POST request:

https://www.payfast.co.za/onsite/process

Response:

{
  "uuid": "123-abc"
}

Sample code snippet to generate payment identifier

<?php
$passPhrase = 'jt7NOE43FZPn';
$data = [
    'merchant_id' => '10000100',
    'merchant_key' => '46f0cd694581a',
    // Additional required payment data here...
];

// Helper function to convert data array to query string
function dataToString($dataArray) {
    $pfOutput = '';
    foreach ($dataArray as $key => $val) {
        if ($val !== '') {
            $pfOutput .= $key . '=' . urlencode(trim($val)) . '&';
        }
    }
    return substr($pfOutput, 0, -1); // Remove trailing &
}

// Function to call Payfast API and get UUID
function generatePaymentIdentifier($pfParamString, $pfProxy = null) {
    if (in_array('curl', get_loaded_extensions(), true)) {
        $url = 'https://www.payfast.co.za/onsite/process';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $pfParamString);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        if (!empty($pfProxy)) {
            curl_setopt($ch, CURLOPT_PROXY, $pfProxy);
        }
        $response = curl_exec($ch);
        curl_close($ch);
        $rsp = json_decode($response, true);
        if (!empty($rsp['uuid'])) {
            return $rsp['uuid'];
        }
    }
    return null;
}

// Generate signature (see Custom Integration guide for details)
$data["signature"] = generateSignature($data, $passPhrase);

// Convert data to query string
$pfParamString = dataToString($data);

// Generate payment UUID
$identifier = generatePaymentIdentifier($pfParamString);
?>

const axios = require("axios");

const myData = {
  "merchant_id": "10000100",
  "merchant_key": "46f0cd694581a",
  ...
};
const passPhrase = 'jt7NOE43FZPn';

const dataToString = (dataArray) => {
  // Convert your data array to a string
  let pfParamString = "";
  for (let key in dataArray) {
    if(dataArray.hasOwnProperty(key)){pfParamString +=`${key}=${encodeURIComponent(dataArray[key].trim()).replace(/%20/g, "+")}&`;}
  }
  // Remove last ampersand
  return pfParamString.slice(0, -1);
};

const generatePaymentIdentifier = async (pfParamString) => {
  const result = await axios.post(`https://www.payfast.co.za/onsite/process`, pfParamString)
      .then((res) => {
        return res.data.uuid || null;
      })
      .catch((error) => {
        console.error(error)
      });
  console.log("res.data", result);
  return result;
};

// Generate signature (see Custom Integration -> Step 2)
myData["signature"] = generateSignature(myData, passPhrase);

// Convert the data array to a string
const pfParamString = dataToString(myData);

// Generate payment identifier
const identifier = await generatePaymentIdentifier(pfParamString);

import requests
import hashlib
import urllib.parse

myData = {
    'merchant_id':'10000100',
    'merchant_key': '46f0cd694581a',
    ...
    }

def dataToString(dataArray, passPhrase = ''):
    pfParamString = ""
    for key in dataArray:
        # Get all the data from Payfast and prepare parameter string
        pfParamString += key + "=" + urllib.parse.quote_plus(dataArray[key].replace("+", " ")) + "&"
    # After looping through, cut the last & or append your passphrase
    pfParamString = pfParamString[:-1]
    if passPhrase != '':
        pfParamString += f"&passphrase={passPhrase}"
    return pfParamString

def generatePaymentIdentifier(pfParamString):
    url = "https://www.payfast.co.za/onsite/process"
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
        }
    response = requests.post(url, data=pfParamString, headers=headers)
    try:
        responseJson = response.json()
        uuid = responseJson.get('uuid')
        return uuid
    except:
        return False


def generateSignature(dataArray, passPhrase = ''):
    payload = dataToString(dataArray, passPhrase)
    return hashlib.md5(payload.encode()).hexdigest()

# Generate signature
passPhrase = 'jt7NOE43FZPn'
myData["signature"] = generateSignature(myData, passPhrase)

# Convert the data array to a string
pfParamString = dataToString(myData, passPhrase);

# Generate payment identifier
identifier = generatePaymentIdentifier(pfParamString);

curl -X POST \
https://www.payfast.co.za/onsite/process \
-H 'Accept: */*' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Host: transaction.local' \
-H 'accept-encoding: gzip, deflate' \
-H 'cache-control: no-cache' \
-H 'content-length: 246' \
-d
'merchant_id=10000100&merchant_key=46f0cd694581a&item_name=Test%20Item&item_descrip
tion=Test%20Description&amount=100&name_first=Test&name_last=User&email_address=test1
%40test.com&m_payment_id=9876&notify_url=https%3A%2F%2Fnotify.me%2Fof%2Fpayment'

Step 2: Trigger the payment modal popup

After obtaining the uuid, initialize the Payfast payment modal on your checkout page by including the Payfast engine script:

<script src="https://www.payfast.co.za/onsite/engine.js"></script>

Modal initialization options

Method 1: Simple

Trigger the modal with just the UUID:

window.payfast_do_onsite_payment({"uuid":"123-abc"});

Or specify return and cancel URLs:

window.payfast_do_onsite_payment({
  "uuid":"123-abc",
  "return_url":"https://example.com/success",
  "cancel_url":"https://example.com/cancel"
});

On payment success, the buyer is redirected to your return_url.

Method 2: Callback

Provide a callback function to handle success or modal close events programmatically:

window.payfast_do_onsite_payment({"uuid":"123-abc"}, function (result) {
  if (result === true) {
    // Payment completed successfully
  } else {
    // Payment window closed or cancelled
  }
});

Note: When using the callback method, return_url and cancel_url will be ignored.

Payment confirmation

A payment confirmation notification will be sent to the notify_url you specified in your initial request.

For full implementation details, see the Payment Confirmation documentation.