2. Confirm page

The following page outlines a list of fields that need to be submitted in an HTML form from the confirm page. These fields contain all the necessary information needed for PayFast to process a payment.

Note that payment will fail if:

  • any of the required fields are not submitted
  • any of the fields have more characters than allowed
  • any of the fields contain non-allowed characters
  • the signature submitted does not match the signature that the PayFast generates.
  • the order in which the fields are used (to create the signature) does not mirror the order as presented below.
Incorrect signature generation is the cause of most failed integrations.
More information regarding the signature generation and sample code can be found at the bottom of the page.

Confirm page example

The confirm page is usually the last step before the buyer gets to enter their payment details:

confirm-page-example

 

Merchant details

Name Description Include
merchant_id The Merchant ID as given by the PayFast system. Used to uniquely identify the receiving account. This can be found on the merchant’s settings page. required
merchant_key The Merchant Key as given by the PayFast system. Used to uniquely identify the receiving account. This provides an extra level of certainty concerning the correct account as both the ID and the Key must be correct in order for the transaction to proceed. This can be found on the merchant’s settings page. required
1return_url The URL where the user is returned to after payment has been successfully taken.
Default: PayFast homepage
recommended
1cancel_url The URL where the user should be redirected should they choose to cancel their payment while on the PayFast system.
Default: PayFast homepage
recommended
1notify_url The URL which is used by PayFast to post the Instant Transaction Notifications (ITNs) for this transaction. optional
1A variable can be specified globally on your account or overridden on a per transaction basis. The value provided during a transaction overrides the global setting.

 

Buyer details

While these fields are optional, it is highly recommended to provide this information (if available) as it is used to pre-populate any forms the user needs to fill in to complete payment. It decreases the time taken to complete the transaction and improves the rate of successful payment completion .

 

Name Description Include Length
name_first The buyer’s first name. recommended 100 char
name_last The buyer’s last name. recommended 100 char
email_address The buyer’s email address recommended 100 char

 

Transaction details

Name Description Include Length
m_payment_id Unique payment ID on the merchant’s system. recommended 100 char
amount The amount which the payer must pay in ZAR. required
item_name The name of the item being charged for. required 100 char
item_description The description of the item being charged for. recommended 255 char
custom_int1..5 A series of 5 custom integer variables (custom_int1, custom_int2…) which can be used by the merchant as pass-through variables. They will be posted back to the merchant at the completion of the transaction. optional
custom_str1..5 A series of 5 custom string variables (custom_str1, custom_str2…) which can be used by the merchant as pass-through variables. They will be posted back to the merchant at the completion of the transaction. optional 255 char

 

Transaction options

Name Description Include Length
1email_confirmation Whether to send email confirmation to the merchant of the transaction. Email confirmation is automatically sent to the payer. optional
2confirmation_address The address to send the confirmation email to. optional 100 char
  • 1A variable can be specified globally on your account or overridden on a per transaction basis. The value provided during a transaction overrides the global setting.
  • 2This is a Boolean variable whose value must be 1 (on) or 0 (off).

 

Set Payment Method

Name Description Include Length
payment_method Setting the payment method allows for only the desired payment method to be in focus when the buyer lands on the payment page. The values are as follows

  • ‘eft’ – sets eft payment method
  • ‘cc’ – sets credit card payment method
  • ‘dc’ – sets debit card payment method
  • ‘bc’ – sets bitcoin payment method
  • ‘mp’ – sets masterpass payment method
  • ‘mc’ – sets mobicred payment method
optional 3 char

 

Recurring Billing Details

Name Description Include Length
subscription_type The subscription type sets the recurring billing type to either a  subscription or an ad hoc agreement. Values are as follows:

  • 1 – sets type to a subscription
  • 2 – sets type to an ad hoc agreement
required for all subscription types Numeric
1 or 2
billing_date The date from which future subscription payments will be made. Eg. 2016-01-01. Defaults to current date if not set optional for subscription type 1, do not add for type 2 Date format: YYYY-MM-DD
recurring_amount Future recurring amount for the subscription. Defaults to the ‘amount’ value if not set. optional for subscription type 1, do not add for type 2 Numeric and “.”
eg. 123.45
frequency The cycle period. required for subscription type 1, do not add for type 2 Numeric:
3- Monthly
4- Quarterly
5- Biannual
6- Annual
cycles The number of payments/cycles that will occur for this subscription. Set to 0 for infinity. required for subscription type 1, do not add for type 2 Numeric
0 for indefinite subscription

 

Security options

Name Description Include Length
signature A security signature of the transmitted data taking the form of an MD5 hash of the submitted variables. 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 eg. “name_first=John&name_last=Doe&email_address=…” where pairs are listed in the order in which they appear on this page. This hash will be regenerated by the PayFast engine and the values compared to ensure the integrity of the data transfer. optional 32 char

 

Order

The order that you place the variables and urlencoded values in the GET string is important, this order needs to be the same as they appear in the tables above, the reason for this is that a signature is going to be generated on the payfast payment engine using the supplied variables in this set order and the resulting hash values need to match in order for the user to proceed with their payment. 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 eg.:

name_first=John&name_last=Doe&email_address=...

Passphrase

A further security feature used to ‘salt’ the MD5 string used to generate the signature that gets sent through to PayFast to ensure the integrity of the information that is being passed through when payment is made. This is set by yourself in the ‘Settings’ section of the logged in area of the PayFast Dashboard. It is a maximum of 32 characters and does not get passed on to the server other than as part of the string used to generate the signature.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Construct variables 
      $data = array(
          // Merchant details
          'merchant_id' => '',
          'merchant_key' => '',
          'return_url' => 'http://www.yourdomain.co.za/thank-you.html',
          'cancel_url' => 'http://www.yourdomain.co.za/cancelled-transction.html',
          'notify_url' => 'http://www.yourdomain.co.za/itn.php',
	          'name_first' => 'First Name',
	          'name_last'  => 'Last Name',
	          'email_address'=> 'valid@email_address.com',
	          'm_payment_id' => '8542', //Unique payment ID to pass through to notify_url
	          'amount' => number_format( sprintf( ".2f", $cartTotal ), 2, '.', '' ), //Amount needs to be in ZAR, 
          if you have a multicurrency system, the conversion needs to place before building this array 
          'item_name' => 'Item Name',
          'item_description' => 'Item Description',
          'custom_int1' => '9586', //custom integer to be passed through           
          'custom_str1' => 'custom string to be passed through with the transaction to the notify_url page'            
          );        
 
      // Create GET string
      foreach( $data as $key => $val )
      {
          if(!empty($val))
          {
          	$pfOutput .= $key .'='. urlencode( trim( $val ) ) .'&';
          }
  	}
      // Remove last ampersand
      $getString = substr( $pfOutput, 0, -1 );
      if( isset( $passPhrase ) )
      {
          $getString .= '&passphrase='.$passPhrase;
      }	
      $data['signature'] = md5( $getString );

This array can then also be used in generating the form output.

1
2
3
4
5
      // If in testing mode use the sandbox domain ?  sandbox.payfast.co.za else www.payfast.co.za
      $testingMode = true;
      $pfHost = $testingMode ? 'sandbox.payfast.co.za' : 'www.payfast.co.za';
      $htmlForm = '
<form action="https://'.$pfHost.'/eng/process" method="post">'; foreach($data as $name=> $value) { $htmlForm .= '<input name="'.$name.'" type="hidden" value="'.$value.'" />'; } $htmlForm .= '<input type="submit" value="Pay Now" /></form>'; echo $htmlForm;

 FAQ

Why am I getting a signature mismatch error?

This is most likely caused if you generated the MD5 hashed string with the variables in the wrong order, they need to be in the order as they appear in the tables above. Another reason could be that you have not URLencoded the variable values and trimmed all white spaces off the ends using PHP’s trim() function, or the resultant URLencoding is in lower case (eg. http%3a%2f%2f) instead of the required upper case (eg. http%3A%2F%2F).