9. API

Introduction

PayFast is in the process of rolling out a fully-fledged RESTful API. The first endpoints available will be for the management of subscriptions, with further functionality being released in the near future.

Overview

All API communications with PayFast take the form of standard HTTP requests. These requests are made against a set of endpoints, depending on the action required. Variables may be sent via both the headers and body of each request as specified. The minimum set of variables required to connect to PayFast’s API services are detailed below.
API services follow RESTful principles, and thus rely on HTTP verbs to describe the action being requested:

  • HTTP GET is used retrieve a resource.
  • HTTP PUT is used where an action is required on a resource.
  • HTTP POST is used where a resource needs to be created.
  • HTTP PATCH is used to update all / subset of a resource.

Using the wrong verb for any endpoint will result in a Bad Request (400) error.

Minimum Requirements

At a minimum, the following must be provided to gain access to the API ecosystem:

  1. A valid and an API enabled PayFast merchant account
  2. A passphrase as set on the merchant account settings page
  3. PayFast merchant ID
  4. The version of the API you want to interact with
  5. A valid merchant signature
  6. A timestamp included in the request

Input Formats and Content Types

Sending data to the API may be done in one of two ways:

  • application/x-www-form-urlencoded
    Essentially one big query string where all name / value pairs are separated by the ‘&’ symbol, with an equal (=) symbol between name and value. This is similar to submitting the traditional HTML FORM via POST (eg. frequency=3&cycles=12…).
  • application/json
    Fields should be passed in as a single-level JSON representation, eg:

    {
        "frequency" : 3,
        "cycles" : 12,
        ...
    }

Merchant Signature Generation

The security signature of the transmitted data takes the form of an MD5 hash of the alphabetised submitted variables, header and body variables, as well as the passphrase. The string from which the hash is created is the concatenation of the name value pairs of all the non-blank variables with ‘&’ used as a separator. Each value should also be urlencoded(eg. “email_address=john@doe.com&…&version=v1&passphrase=passphrase”).
The generated MD5 signature must be passed in the header of the request and this hash will be regenerated by the API and compared to ensure the integrity of the data transfer. Example code below:

// $pfData will contain all of the values to be sent to the API, both in the headers and in the body.
$pfData = $fieldsToTransmit;
 
// Construct variables 
foreach( $pfData as $key => $val ) {
    $data[$key] = stripslashes( $val );
}
 
if( isset( $passPhrase ) ) {
    $pfData['passphrase'] = $passPhrase;
}
 
// Sort the array by key, alphabetically
ksort($pfData);
 
// Normalise the array into a parameter string
foreach( $pfData as $key => $val ) {
    if( $key != 'signature' ) {
        $pfParamString .= $key .'='. urlencode( $val ) .'&';
    }
}
 
// Remove the last '&' from the parameter string
$pfParamString = substr( $pfParamString, 0, -1 );
$signature = md5( $pfParamString );
 
// Example comparison should you need to compare a signature sent in by a response from PayFast
if($signature!=$pfData['signature']) {
   die('Invalid Signature');
}

Merchant Passphrase

The signature described previously utilises a passphrase that is chosen by the merchant and is linked to their account. Every request sent by the merchant will have a signature that is salted with their passphrase. The passphrase is considered a secret between the merchant and PayFast and should never be sent or given out. A passphrase must be set by the merchant before any API interaction is allowed. The merchant may set their own passphrase by:

  1. Login to PayFast using their merchant credentials.
  2. Clicking on ‘Settings’, and then ‘Edit’ under the ‘Security Pass Phrase’ section.
  3. Inputting the desired passphrase, and clicking ‘Update’

Request Timestamp

Each request to the API must contain an ISO-8601 formatted timestamp. This field must be present in each request body along with the signature. Failure to include this field will result in an error. The timestamp field must be formatted according to ISO-8601 standards, and be in the following format:
YYYY-MM-DDTHH:MM[(+-)HH:MM] (e.g. 2016-04-01T12:00:01+02:00)
The time zone offset group ((+-)HH:MM) is optional. If not included, the default will be assumed to be GMT +2

IP Whitelisting

Each request to the API may be controlled by an IP address whitelist. If set, the IP address of the server completing the API call must be in the given list, else the action will not be processed. The whitelist can be set on the merchant’s settings page and is an optional security setting.