If no duration is provided, PayFast pauses for 1 cycle by default.

Endpoint

PUT https://api.payfast.co.za/subscriptions/{{token}}/pause

Same host for sandbox; append ?testing=true to the 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.

Body parameters

Field	Type	Required	Description
`cycles`	integer	No	Number of billing cycles to pause. Default: 1 if omitted.

You may send the body as application/json or application/x-www-form-urlencoded (see examples below).

Required headers

Header	Type	Required	Description
`merchant-id`	integer (8 chars)	✅	Your Merchant ID. ([PyPI][3])
`version`	string	✅	API version (e.g., `v1`). ([PyPI][3])
`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 + body you send, plus passphrase; exclude signature and (in sandbox) testing.

Signature — canonical string (copy/paste)

If sending JSON body (e.g., {"cycles":2}):

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

Headers-only (omitting cycles defaults to 1 cycle):

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

(URL-encode all values; exclude signature and testing.)

Examples

JSON (sandbox)

curl -X PUT "https://api.payfast.co.za/subscriptions/6b9b1fcd-1793-48ca-a659-136ec66ad320/pause?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T10:05:00+02:00" \
  -H "signature: ae9467a91e5ce13951ec2e3b77a00484" \
  -H "Content-Type: application/json" \
  -d '{"cycles": 2}'

Form-encoded (sandbox)

curl -X PUT "https://api.payfast.co.za/subscriptions/6b9b1fcd-1793-48ca-a659-136ec66ad320/pause?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T10:05:00+02:00" \
  -H "signature: ae9467a91e5ce13951ec2e3b77a00484" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "cycles=2"

Example response

{
    "code": 200,
    "status": "success",
    "data": {
        "response": true,
        "message": "Success"
    }
}

You'll see "paused" displayed as the **subscription status **on the Sandbox dashboard's subscription page.

Notes & gotchas

Not providing cycles pauses 1 billing cycle by default.
Pausing delays future billing but does not cancel the subscription. Use Cancel to end it.
Ensure your timestamp includes a timezone offset and is freshly generated.
In sandbox, append ?testing=true to the URL but do not hash it.
Path params (like :token) are not included in the signature string.