Endpoint

GET https://api.payfast.co.za/subscriptions/{{adhoc_token}}/adhoc?testing=true

Sandbox uses the same host; append ?testing=true (do not include testing in the signature).

Path parameter

Name	Type	Description
`token`	string	Subscription token associated with the ad-hoc tokenization agreement.

Query parameters

Name	Type	Required	Description
`testing`	bool	No	Sandbox only: `testing=true`. Exclude from signature.

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]` (include offset).
`signature`	string (MD5)	✅	Lower-case MD5 of canonical string (see below).

Signature scope: headers you send + passphrase; exclude signature and (sandbox) testing. Path params are not signed.

Signature — canonical string (copy/paste)

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

Example (sandbox)

curl -X GET "https://api.payfast.co.za/<EXACT_PATH_FROM_COLLECTION_WITH_TOKEN>?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T14:05:00+02:00" \
  -H "signature: da685ec3b13fe8ad9e05528c4fce3690"

Response

Standard JSON envelope with agreement status/details.

{
    "code": 200,
    "status": "success",
    "data": {
        "response": {
            "status": 1,
            "status_reason": "",
            "status_text": "ACTIVE"
        }
    }
}

Try It

🔗
Related: Ad-hoc charge