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]: A 36 character alphanumeric string which uniquely identifying 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: none
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-04T00:00:00”}}}
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-04T00:00:00”}}}
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 Name Validation
merchant-id Numeric
version Alphanumeric
timestamp Alphanumeric, ISO-8601 date and time
YYYY-MM-DDTHH:MM:SS[+HH:MM]
signature Alphanumeric (see API signature generation)
amount Numeric – amount in cents and not X.XX
cycles Numeric
0 – Infinite cycles
cycles_complete Numeric
frequency Numeric
3 – Monthly
4 – Quarterly
5 – Bi-Annually
6 – Annually
item_description Alphanumeric & “- : ‘ ” ( ) @ . , _ ; # ’ | [space] \n \r”
item_name Alphanumeric & “- : ‘ ” ( ) @ . , _ ; # ’ | [space] \n \r”
itn 0 – false
1 – true
run_date YYYY-MM-DD
status Numeric
1 – Active
2 – Cancelled
3 – Paused
4 – Complete
5 – Retry
6 – Failed
7 – System
token Alphanumeric & “-“

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 Code Error Message Reason
400 Required variables not present in request The request is missing some or all of the required fields.
Value for signature is not in the expected format Generated when the merchant signature provided is not an MD5 hash, or is malformed.
API version is not valid Issued when the version header refers to a version that does not exist, or is malformed.
Signature not present in headers The signature has not been provided.
401 Merchant not found The given merchant ID was not found.
Request origin not recognised Generated when the request does not contain a REMOTE_ADDR value.
Request origin could not be verified Occurs when the request is made from a location not specified in the whitelist.
Merchant authorisation failed The signature is incorrect.
404 Service / endpoint not found The endpoint does not exist or the requesting merchant does not have permission to access.
429 Signature rate limit reached, please try again in a few minutes The rate limit was hit.
500 Application Error Application Error
Communication Failure Networking issue with the API