Step 2: Create Security Signature

That signature, crafted using a shared secret, serves as a digital fingerprint, guaranteeing the transaction's authenticity and shielding it from tampering.

Signatures reduce tampering risk; see PCI page for broader security obligations

This signature is passed as a hidden field in your HTML form:

<input type="hidden" name="signature" value="f103e22c0418655fb03991538c51bfd5">

How the signature is generated

The signature is an MD5 hash of the transaction data, built using the following steps:

❗️
If the fica_idnumber field is used, place it as the **final field ** in the form, before the signature.

1. Concatenate non-blank variables

Concatenate all non-empty name-value pairs using an ampersand (&) as a separator. The variables must be in the same order as they are described in the integration documentation — not alphabetically.

⚠️
Do not use the API signature format (alphabetical ordering). Use the order of appearance in the form fields instead.

Example:

name_first=John&name_last=Doe&email_address=john@example.com

2. Append the passphrase

If a passphrase is configured in the Payfast dashboard under Settings, append it to the string using:

&passphrase=your_passphrase

Result:

📘
The passphrase acts as a salt to strengthen the security of the signature.

3. URL encode the string

URL-encode the full string using the following rules:

All characters must be uppercase-encoded (e.g. http:// becomes HTTP%3A%2F%2F)
Spaces must be encoded as +

4. Generate the MD5 hash

Apply MD5 hashing to the encoded string to generate the final signature.

This signature is then added to the form:

<input type="hidden" name="signature" value="md5_hashed_signature">

Sample PHP function

Here's a working PHP function to generate the signature:

<?php
/**
 * Generates Payfast MD5 signature
 * 
 * @param array $data        // Form data
 * @param string|null $passPhrase // Optional passphrase
 * @return string
 */
function generateSignature($data, $passPhrase = null) {
    // Create parameter string from non-empty fields
    $pfOutput = '';
    foreach ($data as $key => $val) {
        if ($val !== '') {
            $pfOutput .= $key . '=' . urlencode(trim($val)) . '&';
        }
    }

    // Remove trailing '&'
    $getString = substr($pfOutput, 0, -1);

    // Append passphrase if present
    if ($passPhrase !== null) {
        $getString .= '&passphrase=' . urlencode(trim($passPhrase));
    }

    // Return MD5 hash
    return md5($getString);
}
?>

const crypto = require("crypto");

const generateSignature = (data, passPhrase = null) => {
  // Create parameter string
  let pfOutput = "";
  for (let key in data) {
    if(data.hasOwnProperty(key)){
      if (data[key] !== "") {
        pfOutput +=`${key}=${encodeURIComponent(data[key].trim()).replace(/%20/g, "+")}&`
      }
    }
  }

  // Remove last ampersand
  let getString = pfOutput.slice(0, -1);
  if (passPhrase !== null) {
    getString +=`&passphrase=${encodeURIComponent(passPhrase.trim()).replace(/%20/g, "+")}`;
  }

  return crypto.createHash("md5").update(getString).digest("hex");
};

import hashlib
import urllib.parse

pfData = {
    "merchant_id": "10000100",
    "merchant_key": "46f0cd694581a",
    "return_url": "https://www.example.com",
    "notify_url": "https://www.example.com/notify_url",
    "m_payment_id": "UniqueId",
    "amount": "200",
    "item_name": "test product"
}

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

passPhrase = 'jt7NOE43FZPn'
signature = generateSignature(pfData, passPhrase)

Troubleshooting

If your integration fails due to a signature mismatch, consult the guide below for common causes and fixes:

Troubleshooting Signature Mismatches

Test your Security Signature (Sandbox)

Open the Signature troubleshooter: https://sandbox.payfast.co.za/integration-tools

Build the “Payload String”

Start with the exact fields you POST to Payfast. Omit signature and any empty/null values.
Preserve the same field order your code uses.
- If you sort with ksort (or similar), use alphabetical order.
- If you don’t sort, keep your form/insertion order (e.g. merchant_id, merchant_key, return_url, cancel_url, notify_url, amount, item_name).
Use the same URL-encoding your code uses.
- PHP default/form encoding: spaces become +.
- RFC 3986 (e.g., JS encodeURIComponent or PHP_QUERY_RFC3986): spaces become %20.
Join as key=value pairs with & between pairs.If you have a passphrase, append it last: &passphrase=... (URL-encoded).
Paste the full string into Payload String on the Sandbox page and click Test signature matching.

Example (form encoding, matches many PHP defaults)

merchant_id=10000100&merchant_key=46f0cd694581a&return_url=https%3A%2F%2Fexample.com%2Freturn&cancel_url=https%3A%2F%2Fexample.com%2Fcancel&notify_url=https%3A%2F%2Fexample.com%2Fitn&amount=49.95&item_name=Test+Item

Same example (RFC 3986 encoding)

merchant_id=10000100&merchant_key=46f0cd694581a&return_url=https%3A%2F%2Fexample.com%2Freturn&cancel_url=https%3A%2F%2Fexample.com%2Fcancel&notify_url=https%3A%2F%2Fexample.com%2Fitn&amount=49.95&item_name=Test%20Item

If the tester says “parameter order incorrect”: rebuild the string in the exact order your code used to hash the signature (don’t re-sort just for the tester).

Minimal helper snippets (optional)

PHP (choose your encoding + keep/order keys accordingly)

function buildPayload(array $data, ?string $passphrase = null, bool $rfc3986 = false): string {
    unset($data['signature']);
    $data = array_filter($data, fn($v) => $v !== '' && $v !== null);

    // If your code sorts before hashing, keep this:
    // ksort($data);

    $mode = $rfc3986 ? PHP_QUERY_RFC3986 : PHP_QUERY_RFC1738; // RFC1738 => spaces as '+'
    $base = http_build_query($data, '', '&', $mode);
    return $passphrase ? $base . '&passphrase=' . rawurlencode($passphrase) : $base;
}

function buildPayload(data, passphrase, usePlusSpaces=false) {
  const entries = Object.entries(data).filter(([k,v]) => k !== 'signature' && v != null && v !== '');
  // If your code sorts before hashing, keep this sort:
  // entries.sort(([a],[b]) => a.localeCompare(b));

  let s = entries.map(([k,v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&');
  if (passphrase) s += `&passphrase=${encodeURIComponent(passphrase)}`;
  return usePlusSpaces ? s.replace(/%20/g, '+') : s; // form-style if needed
}