Ad-hoc subscription

Create a one-off debit against an existing subscription token. This runs outside the normal billing schedule (useful for add-ons, catch-ups, or manual adjustments).

Endpoint

POST https://api.payfast.co.za/subscriptions/{{adhoc_token}}/adhoc

For sandbox, append ?testing=true to the URL (do not include testing in the signature).

Path parameter

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

👍
In the provided example, we successfully executed an ad-hoc charge for Tokenization, employing the token 'dabe70d0-52ae-47d8-8538-dee2544d6ab4,' which is now displayed on the Transactions page.

Body parameters

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

Field	Type	Required	Constraints / Description
`amount`	integer	✅	In cents (ZAR), no decimals. Example: `19900` = R199.00.
`item_name`	string	✅	Max 100 chars. Short title for the charge line.
`item_description`	string	No	Max 255 chars. Longer description for the line item.
`itn`	boolean	No	Send ITN for this charge. Default true. Set `false` to suppress.
`m_payment_id`	string	No	Max 100 chars. Your unique reference/ID (useful for reconciliation/idempotency semantics on your side).
`cc_cvv`	numeric	No	Card CVV (3/4 digits) — only if required by your account/configuration.
`setup`	string (JSON-encoded)	No	Additional attributes (e.g., Split Payments). Provide a JSON string; it will be URL-encoded in the signature. See Split Payments docs for structure.

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 + body you send plus your passphrase; exclude signature and (in sandbox) testing. Path params like :token are not included.

Signature — canonical string (copy/paste)

JSON body (e.g., {"amount": 199.00}):

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

Form-encoded body (amount=199.00) produces the same canonical line as above.

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

Examples

JSON (sandbox)

curl -X POST "https://api.payfast.co.za/subscriptions/REPLACE_TOKEN/adhoc?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T13:45:00+02:00" \
  -H "signature: <md5-of-canonical-string>" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 19900,
        "item_name": "Widget Topup",
        "item_description": "Addon widgets for August",
        "itn": true,
        "m_payment_id": "ORD-100045",
        "cc_cvv": 123,
        "setup": {"split_payments":[{"merchant_id":"10000100","amount":9900}]}
      }'

Form-encoded (sandbox)

curl -X POST "https://api.payfast.co.za/subscriptions/REPLACE_TOKEN/adhoc?testing=true" \
  -H "merchant-id: 10000000" \
  -H "version: v1" \
  -H "timestamp: 2025-08-27T13:45:00+02:00" \
  -H "signature: <md5-of-canonical-string>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=19900" \
  --data-urlencode "item_name=Widget Topup" \
  --data-urlencode "item_description=Addon widgets for August" \
  --data-urlencode "itn=true" \
  --data-urlencode "m_payment_id=ORD-100045" \
  --data-urlencode "cc_cvv=123" \
  --data-urlencode "setup={\"split_payments\":[{\"merchant_id\":\"10000100\",\"amount\":9900}]}"

Example response

Standard envelope indicating success/failure and the resulting transaction outcome.

{
    "code": 200,
    "status": "success",
    "data": {
        "response": "true",
        "message": "Transaction was successful\r\n(00)",
        "pf_payment_id": 2760768
    }
}

💳
Where will this charge appear?

Transactions: One-time (ad-hoc) charges show here as their own rows — just like normal renewal charges.

Subscriptions: Shows the subscription’s status and schedule (next run date, paused/cancelled), not the ledger of charges.

Tokenization: Lists the tokenization agreement (permission to charge). You can fetch/cancel it here, but charges themselves do not list on this screen.

👍
In the provided example, we successfully executed an ad-hoc charge for Tokenization, employing the token 'dabe70d0-52ae-47d8-8538-dee2544d6ab4,' which is now displayed on the **Transactions **page.

See it display under the list of Transactions.

Notes & gotchas

Ad-hoc charges run immediately and are separate from scheduled cycles.
Ensure your timestamp is fresh and includes a timezone offset.
In sandbox, append ?testing=true but do not hash it.
If you receive 401 Merchant authorisation failed, re-check passphrase, timestamp, and URL-encoding in the canonical string.

🔐
New to signing? See Authentication & Signature. For error meanings, see Errors.