The signature serves as a digital fingerprint, verifying the integrity of the data and confirming its origin. This mechanism ensures that each transaction is securely processed, safeguarding both your business and your customers.

🔐
Keep your passphrase secret. Store it only in local env/“Current Value” fields (e.g., Postman), never commit it to version control.

Merchant passphrase

Set (or rotate) your passphrase in your merchant account:

Log in to PayFast.
Go to Settings → Security Pass Phrase → Edit.
Enter your desired passphrase → Update.

A passphrase must be set before any API interaction is allowed.

Required headers

Header	Type	Required	Description
`merchant-id`	integer (8 chars)	✅	Your PayFast Merchant ID.
`version`	string	✅	API version (e.g. `v1`).
`timestamp`	ISO-8601 string	✅	`YYYY-MM-DDTHH:MM:SS[+HH:MM]` (must include offset).
`signature`	string (MD5)	✅	Lower-case MD5 of the canonical string (see below).

Signature generation rules

Collect all non-empty fields being submitted (exclude signature itself).
If using Custom Integration (HTML form): keep fields in form order.
If using API requests: sort fields alphabetically by key.
URL-encode all values.
Join as key=value&key=value (no trailing &).
Append passphrase=<your_passphrase> (participates in the hash but is not sent).
Generate an MD5 hash of the final string and send the lowercase hex as signature.

ABSA/Capitec note (ID number)

If you include an ID number field (for example fica_idnumber) and receive Signature Mismatch, append the ID number field at the end of the signature string (just before the passphrase).

💡
Do not include signature itself, and in sandbox do not include testing=true in the string you hash.

Canonical string (copy/paste)

Headers-only (no body fields):

merchant-id=<MERCHANT_ID>&passphrase=<PASSPHRASE>&timestamp=<TIMESTAMP_ENC>&version=<VERSION>

Example with URL-encoded timestamp:

merchant-id=10000000&passphrase=•••&timestamp=2025-08-26T08%3A00%3A00%2B02%3A00&version=v1

<TIMESTAMP_ENC> is your timestamp after URL-encoding (include the timezone offset).

Quick example (cURL)

curl -X GET "https://api.payfast.co.za/ping?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-26T08:00:00+02:00" \
  -H "signature: <md5-of-canonical-string>"

Code examples

PHP

<?php
/**
 * Generate signature for API
 * @param array $pfData (all header + body + query values being sent)
 * @param string|null $passPhrase
 * @return string MD5 lower-case hex
 */
function generateApiSignature($pfData, $passPhrase = null) {
    if ($passPhrase !== null) {
        $pfData['passphrase'] = $passPhrase;
    }
    // Sort alphabetically by key
    ksort($pfData);
    // Build query-string style payload (values URL-encoded)
    $payload = http_build_query($pfData);
    // MD5 as lower-case hex
    return md5($payload);
}

const crypto = require("crypto");

function md5Signature(fields, passphrase) {
  const data = { ...fields, passphrase };
  const encoded = Object.keys(data)
    .filter(k => data[k] !== undefined && data[k] !== "" && k !== "signature" && k !== "testing")
    .sort()
    .map(k => `${k}=${encodeURIComponent(String(data[k]))}`)
    .join("&");
  return crypto.createHash("md5").update(encoded).digest("hex"); // lower-case
}

// Usage:
const headers = {
  "merchant-id": "10000000",
  version: "v1",
  timestamp: "2025-08-26T08:00:00+02:00",
};
const signature = md5Signature(headers, process.env.PAYFAST_PASSPHRASE);

import hashlib, urllib.parse

def md5_signature(fields: dict, passphrase: str) -> str:
    data = {**fields, "passphrase": passphrase}
    items = [(k, v) for k, v in data.items()
             if v not in (None, "") and k not in ("signature", "testing")]
    items.sort(key=lambda kv: kv[0])
    payload = "&".join(f"{k}={urllib.parse.quote(str(v), safe='')}" for k, v in items)
    return hashlib.md5(payload.encode("utf-8")).hexdigest()  # lower-case

# Example:
headers = {
    "merchant-id": "10000000",
    "version": "v1",
    "timestamp": "2025-08-26T08:00:00+02:00",
}
sig = md5_signature(headers, "<PASSPHRASE>")

Postman (minimal pre-request)

// Timestamp with offset, no ms
function isoNoMsWithOffset(d=new Date()){
  const p=n=>String(n).padStart(2,'0'), off=-d.getTimezoneOffset();
  const s=off>=0?'+':'-', hh=p(Math.floor(Math.abs(off)/60)), mm=p(Math.abs(off)%60);
  return `${d.getFullYear()}-${p(d.getMonth()+1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}${s}${hh}:${mm}`;
}
pm.variables.set('timestamp', isoNoMsWithOffset());

const passphrase = pm.variables.get('passphrase');
let fields = {
  'merchant-id': pm.variables.get('merchant-id'),
  'version': pm.variables.get('version') || 'v1',
  'timestamp': pm.variables.get('timestamp')
};
pm.request.url.query.each(q => { if(!q.disabled) fields[q.key]=q.value; });
if (pm.request.body && pm.request.body.mode === 'urlencoded') {
  pm.request.body.urlencoded.each(i => { if(!i.disabled) fields[i.key]=i.value; });
}
fields.passphrase = passphrase;

const payload = Object.entries(fields)
  .filter(([k,v]) => v!=='' && v!=null && k!=='signature' && k!=='testing')
  .sort((a,b)=>a[0].localeCompare(b[0]))
  .map(([k,v]) => `${k}=${encodeURIComponent(String(v))}`)
  .join('&');

pm.variables.set('signature', CryptoJS.MD5(payload).toString());

Common pitfalls

Using live passphrase in sandbox (or vice-versa).
Timestamp missing offset or too old; generate a fresh one per call.
Not URL-encoding values in the canonical string.
Including testing=true or signature in the string you hash.
MD5 hex not lower-case.

📘
Test connectivity with Ping (use ?testing=true in sandbox). See Errors for code meanings and quick fixes.