9.1 Subscription Payments API Endpoints

URL Composition

The API exposes the following endpoints which will allow Merchants the ability to interact with subscriptions on their accounts. URLs to interact with take the following form:

https://api.payfast.co.za/[endpoint]/[token]/[action]?testing=true

  • [endpoint]: This should be set to “subscriptions”.
  • [token]: The 36 character alphanumeric string returned to your notify URL via the ITN callback which uniquely identifies a subscription.
  • [action]: This will be the verb describing the intended action to take.
  • ?testing=true: Include this text should you wish to make use of the PayFast sandbox for testing purposes.

Available Actions

The actions described below are available via the API.

If using a FORM to post data to any endpoint, all FORMs must submit via normal POST forms and have a hidden value called ‘_method’, set to the appropriate verb.

Recurring Billing Type 1 – Subscription Payments

[GET] /ping
Description: Used to check if the API is responding to requests
Required payload: Header: merchant-id, version, timestamp, signature
           Body: none
Optional Payload: None
Successful response: HTTP 200, Body contains JSON string “true”.
Unsuccessful response: Validation error on payload, or HTTP Status 404

[PUT] /pause
Description: ‘Freeze’ a subscription, for a duration indicated by a ‘cycles’ payload variable.
Required payload: Header: merchant-id, version, timestamp, signature
           Body: none
Optional Payload: cycles (default is 1 if not given)
Successful response: HTTP 200, {“code”:200,”status”:”success”,”data”:{“response”:true}}
Unsuccessful response: Validation error on payload, or {“code”:500,”status”:”error”,”data”:{“response”:false}}

[PUT] /unpause
Description: ‘Unfreeze’ a subscription.
Required payload: Header: merchant-id, version, timestamp, signature
           Body: none
Optional Payload: None
Successful response: HTTP 200, {“code”:200,”status”:”success”,”data”:{“response”:true}}
Unsuccessful response: Validation error on payload, or {“code”:500,”status”:”error”,”data”:{“response”:false}}

[PUT] /cancel
Description: This will cancel a subscription entirely.
Required payload: Header: merchant-id, version, timestamp, signature
           Body: none
Optional Payload: None
Successful response: HTTP 200, {“code”:200,”status”:”success”,”data”:{“response”:true}}
Unsuccessful response: Validation error on payload, or {“code”:500,”status”:”error”,”data”:{“response”:false}}

[PATCH] /update
Description: This allows for multiple subscription values to be updated.
Required payload: Header: merchant-id, version, timestamp, signature
           Body: At least one of the optional payload
Optional Payload: cycles, frequency, date, amount
Successful response: HTTP 200,
            {“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”}}}
Unsuccessful response: Validation error on payload, or {“code”:500,”status”:”error”,”data”:{“response”:false}}

[GET] /fetch
Description: Returns a JSON object containing the subscription details.
Required payload: Header: merchant-id, version, timestamp, signature
           Body: none
Optional Payload: None
Successful response: HTTP 200,
            {“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”}}}
Unsuccessful response: Validation error on payload, or {“code”:500,”status”:”error”,”data”:{“response”:false}}

API Validation

All fields are validated. If an optional field is supplied, it too will be validated.

Field NameValidation
merchant-idNumeric
versionAlphanumeric
timestampAlphanumeric, ISO-8601 date and time
YYYY-MM-DDTHH:MM:SS[+HH:MM]
signatureAlphanumeric (see API signature generation)
amountNumeric – amount in cents and not X.XX
cyclesNumeric
0 – Infinite cycles
cycles_completeNumeric
frequencyNumeric
3 – Monthly
4 – Quarterly
5 – Bi-Annually
6 – Annually
item_descriptionAlphanumeric & “- : ‘ ” ( ) @ . , _ ; # ’ | [space] \n \r”
item_nameAlphanumeric & “- : ‘ ” ( ) @ . , _ ; # ’ | [space] \n \r”
itn0 – false
1 – true
run_dateYYYY-MM-DD
statusNumeric
1 – Active
2 – Cancelled
3 – Paused
4 – Complete
5 – In Review
6 – Failed
7 – System
tokenAlphanumeric & “-“

Note: The amount field in the API is in cents and not decimal notation as per normal PayFast integrations.

CURL Examples

The examples below demonstrate cURL calls containing the following:

  • HTTP Method: PUT
  • URL: https://api.payfast.co.za/
  • Endpoint: subscriptions/[Token]/[Action]

The calls are made to v1 (version 1) of the API. The merchant-id, version, timestamp and signature are all included as request headers.

Pausing a subscription:

curl -v -X PUT -H “merchant-id: 10000100” -H “version: v1” -H “timestamp=2016-04-01T12:00:01”
-H “signature=840654b40a8b312e54650e1613696b44”
https://api.payfast.co.za/subscriptions/a3b3ae55-ab8b-b388-df23-4e6882b86ce0/pause

An example of the request information sent can be seen below:

> PUT https://api.payfast.co.za/subscriptions/a3b3ae55-ab8b-b388-df23-4e6882b86ce0/pause HTTP/1.1
> User-Agent: curl/7.37.0
> Host: api.payfast.co.za
> Accept: */*
> merchant-id: 10000100
> version: v1
> timestamp: 2016-04-01T12:00:01
> signature: 840654b40a8b312e54650e1613696b44
> Content-Length: 0
> Content-Type: application/x-www-form-urlencoded

Return Variables

All responses from the API follow a standard format. It is a JSON encoded string containing code, status and data elements. The data element may contain more than one message.

Example of a JSON formatted response:

  • code : The HTTP status code for the result
  • status : A more verbose description of the result
  • data : Will contain a response of either true or false for the action and may also contain one or more description(s) for the reason of the result

Example of a success response:

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

Example of a failure response

{
	"code": 400,
	"status": "failed",
	"data": {
		"response": false,
                                   "message": "Failure"
	}
}

Errors and Causes

The following errors can be expected during authentication when connecting to PayFast.

Error CodeError MessageReason
400Required variables not present in requestThe request is missing some or all of the required fields.
Value for signature is not in the expected formatGenerated when the merchant signature provided is not an MD5 hash, or is malformed.
API version is not validIssued when the version header refers to a version that does not exist, or is malformed.
Signature not present in headersThe signature has not been provided.
401Merchant not foundThe given merchant ID was not found.
Request origin not recognisedGenerated when the request does not contain a REMOTE_ADDR value.
Request origin could not be verifiedOccurs when the request is made from a location not specified in the whitelist.
Merchant authorisation failedThe signature is incorrect.
404Service / endpoint not foundThe endpoint does not exist or the requesting merchant does not have permission to access.
429Signature rate limit reached, please try again in a few minutesThe rate limit was hit.
500Application ErrorApplication Error
Communication FailureNetworking issue with the API