Returns a JSON object with the subscription’s latest state.

Endpoint

GET https://api.payfast.co.za/subscriptions/{{token}}/fetch

Use the same host for sandbox and append ?testing=true to the request URL (do not include testing in the signature).

Path parameter

Name	Type	Description
`token`	string	Subscription token you received from PayFast (via ITN/notification) and must use for all subsequent subscription API calls.

You can also find the subscription **token ** on the Subscriptions screen of your Sandbox dashboard.

Query parameters

Name	Type	Required	Description
`testing`	bool	No (sandbox only)	Set `testing=true` when calling the sandbox. 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 the canonical string (see below).

Signature scope: sign the headers and body you send plus passphrase; exclude signature and testing. Path params (like {{token}}) are not part of the signature.

Signature — 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

Example request (sandbox)

curl -X GET "https://api.payfast.co.za/subscriptions/6b9b1fcd-1793-48ca-a659-136ec66ad320/fetch?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-26T08:00:00+02:00" \
  -H "signature: e0616ed7dde840f97ec08b21b1576323"

Example response

Returns a JSON object with subscription details (status, schedule, etc.). Exact fields may vary; handle unknown keys defensively.

{
    "code": 200,
    "status": "success",
    "data": {
        "response": {
            "amount": 49956,
            "cycles": 12,
            "cycles_complete": 1,
            "frequency": 3,
            "run_date": "2025-09-01T00:00:00+02:00",
            "status": 1,
            "status_reason": "",
            "status_text": "ACTIVE",
            "token": "6b9b1fcd-1793-48ca-a659-136ec66ad320"
        }
    }
}

Notes & gotchas

Use the token provided via PayFast notifications/ITN for all subscription calls.
In sandbox, call with ?testing=true but do not include it in the signature.
Ensure timestamp includes a timezone offset and is freshly generated per call.

🔐
New to signing? See Authentication & Signature for the algorithm and examples.

🧭
Troubleshooting? Check Errors for common codes like 401 Merchant authorisation failed.