Typical updates include amount, frequency, number of cycles, and the next payment date.

Endpoint

PATCH https://api.payfast.co.za/subscriptions/{{token}}/update

Use the same host for sandbox; append ?testing=true to the request URL (do not include testing in the signature). PayFast clients and SDKs reference this endpoint.

Path parameter

Name	Type	Description
`token`	string	Subscription token (from PayFast notifications/ITN) used for all subsequent subscription API calls.

Body parameters

Send as application/json or application/x-www-form-urlencoded.

Field	Type	Required	Description
`amount`	number	No	New recurring amount for the subscription.
`frequency`	integer	No	New billing frequency. (Use PayFast’s accepted frequency codes.)
`cycles`	integer	No	New total/remaining number of billing cycles.
`next_run_date`	string	No	Next payment date to apply (ISO-8601 date/time with offset).
(others)			Additional fields may be supported by account configuration. Handle unknown fields defensively.

On the PayFast Dashboard, merchants can edit amount, frequency, cycles, and next payment date—these map to what’s typically supported by the API.

Required headers

Header	Type	Required	Description
`merchant-id`	integer (8 chars)	✅	Your 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 scope: sign the headers + body you send plus your passphrase; exclude signature and (in sandbox) testing. Path params (like {{token}}) are not included.

Signature — canonical string (copy/paste)

If sending JSON body (e.g., {"amount": 199.00, "frequency": 3, "next_run_date": "2025-09-01T00:00:00+02:00"}):

amount=199.00&frequency=3&merchant-id=<MERCHANT_ID>&next_run_date=2025-09-01T00%3A00%3A00%2B02%3A00&passphrase=<PASSPHRASE>&timestamp=<TIMESTAMP_ENC>&version=<VERSION>

Headers-only (no body fields):

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

Remember: URL-encode every value in the canonical string (e.g., + → %2B, : → %3A). Do not include testing=true.

Examples

JSON (sandbox)

curl -X PATCH "https://api.payfast.co.za/subscriptions/REPLACE_TOKEN/update?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T12:10:00+02:00" \
  -H "signature: <md5-of-canonical-string>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 199.00, "frequency": 3, "next_run_date": "2025-09-01T00:00:00+02:00"}'

Form-encoded (sandbox)

curl -X PATCH "https://api.payfast.co.za/subscriptions/REPLACE_TOKEN/update?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T12:10:00+02:00" \
  -H "signature: <md5-of-canonical-string>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=199.00" \
  --data-urlencode "frequency=3" \
  --data-urlencode "next_run_date=2025-09-01T00:00:00+02:00"

Example response

Standard response envelope indicating success/failure and updated subscription state.

{
    "code": 200,
    "status": "success",
    "data": {
        "response": {
            "token": "a3b3ae55-ab8b-b388-df23-4e6882b86ce0",
            "amount": 1628,
            "cycles": 14,
            "cycles_complete": 9,
            "frequency": 3,
            "status": 1,
            "run_date": "2016-07-04"
        }
    }
}

Notes & gotchas

Make sure you’re using the correct environment passphrase (sandbox vs live).
Timestamp must be fresh and include a timezone offset.
Always URL-encode values in your canonical string; hex must be lower-case.
If you get 401 Merchant authorisation failed, re-check passphrase, timestamp, and signature string steps.
Endpoint set is documented by PayFast clients/SDKs and support materials; exact field availability can vary by account. Handle unknown keys defensively. ([PyPI][3], [Payfast by Network][1])

🧭
Need a refresher on signing? See Authentication & Signature. For error meanings, see Errors.