Endpoint

GET /process/query/:id

https://api.payfast.co.za/process/query/01d2e4c7-28c8-3a86-151f-eab5357da649
https://api.payfast.co.za/process/query/69

Where :id is either:

pf_payment_id — the PayFast Payment ID for a once-off card transaction, or
token — the Subscription token for a recurring charge (use when the transaction belongs to a subscription).

Sandbox testing: append ?testing=true to the URL while using test credentials.

Examples

Once-off by Payment ID: GET https://api.payfast.co.za/process/query/69
Subscription by Token: GET https://api.payfast.co.za/process/query/01d2e4c7-28c8-3a86-151f-eab5357da649
Sandbox: GET https://api.payfast.co.za/process/query/69?testing=true

Authentication & headers

Include signed headers with every request:

Header	Type	Required	Description
`merchant-id`	integer (8 chars)	Yes	Your PayFast Merchant ID.
`version`	string	Yes	API version (e.g., `v1`).
`timestamp`	ISO-8601 datetime	Yes	`YYYY-MM-DDTHH:MM:SS[+HH:MM]`.
`signature`	string (MD5 hex)	Yes	MD5 of alphabetised submitted header/body variables + passphrase (lower-case hex).

Path parameter

Name	In	Type	Required	Description
`id`	path	string	Yes	The identifier you’re querying. Use `pf_payment_id` for once-off card payments, or `token` for subscription transactions.

Query parameters

Name	In	Type	Required	Description
`testing`	query	bool	No	When `true`, runs the query in sandbox mode.

cURL examples

By PayFast Payment ID (once-off)

curl -X GET "https://api.payfast.co.za/process/query/69" \
  -H "merchant-id: 10000100" \
  -H "version: v1" \
  -H "timestamp: 2025-09-01T08:00:00+02:00" \
  -H "signature: <md5-alphabetised-vars-plus-passphrase>"

By Subscription token

curl -X GET "https://api.payfast.co.za/process/query/01d2e4c7-28c8-3a86-151f-eab5357da649" \
  -H "merchant-id: 10000100" \
  -H "version: v1" \
  -H "timestamp: 2025-09-01T08:00:00+02:00" \
  -H "signature: <md5-alphabetised-vars-plus-passphrase>"

Sandbox (testing=true)

curl -X GET "https://api.payfast.co.za/process/query/69?testing=true" \
  -H "merchant-id: 10000100" \
  -H "version: v1" \
  -H "timestamp: 2025-09-01T08:00:00+02:00" \
  -H "signature: <md5-alphabetised-vars-plus-passphrase>"

Sample response (success)

{
  "code": 200,
  "status": "success",
  "data": {
    "response": {
      "pf_payment_id": 69,
      "m_payment_id": 232345,
      "status": "COMPLETE",
      "amount": 3600,
      "cc_status": "00",
      "cc_message": "Approved or completed successfully (00)"
    },
    "message": "Success"
  }
}

Try It

Field reference (response.response)

Field	Type	Description
`pf_payment_id`	number	PayFast Payment ID for the transaction.
`m_payment_id`	string/number	Your merchant’s own payment reference (if supplied at creation).
`status`	string	Overall transaction state, e.g., `COMPLETE`.
`amount`	number	Transaction amount (unit depends on integration; match your environment’s expectations).
`cc_status`	string	Card processor code (e.g., `00` = approved).
`cc_message`	string	Human-readable description of `cc_status`.

Note: Interpret amount consistently with how you submit/receive values elsewhere in your PayFast integration (minor vs major units).

Notes & troubleshooting

Using the right id:
- Use pf_payment_id for once-off payments.
- Use token for subscription transactions.
Auth failures: Usually due to a missing header or a signature built without alphabetising variables. Ensure MD5 output is lower-case hex.
Testing vs live: Use ?testing=true only with test credentials/data. Remove it for production queries.
Id not found / non-success: Expect a non-200 code or a status value indicating failure; check the message for details.