Developers' API/SCI - receiving payment via JostPay

Table of Contents

1.0 Introduction

This document describes how to receive payment on your website, using JOSTPAY (You must have created a jostpay account before using this tool. .

2.0 Shopping Cart Interface (SCI)

Just as you can access the sci URL directly at // , you can as well embed it in your applications or simple HTML webpages.
When loading the SCI page, the required parameters can be passed to the page through either HTTP GET or POST request methods.

2.1 SCI Parameters

The following parameters can be sent, through HTTP GET or POST request to the URL: //

Input Field Name Description Example Value
merchant Receiver's JOSTPAY ID 149
amount Total amount to be received in NGN 1000
Optional Fields
memo (maximum of 225 characters) Typically the payment description Purchase of XYZ products
ref Unique transaction reference (maximum of 84 characters)
If not supplied, JOSTPAY will automatically generate a unique reference.
But you supply a reference that you have already used for another transaction, an error will occur.
notification_url When a transaction has been completed (either successful or unsuccessful), the transaction reference (under an HTTP POST key 'ref') will be posted to this url (even before the payer gets redirected to the success_url or cancel_url).
It is then advisable to rather perform all the needed confirmation check & updates on this url
success_url After successfuly making the payment, the payer will be redirected back to this url, with the payment data also forwarded in an HTTP POST request
cancel_url If the transaction failed to complete, the payer will be redirected back to this url, with the payment data also forwarded in an HTTP POST request
payment_methods If not supplied, all the payment methods that are available on JOSTPAY will be accessible to the payer. Multiple payment methods can be separated by comma (,). Available options are: card,jostpay,perfectmoney,bitcoin jostpay,perfectmoney,bitcoin
Sample snippets for accessing the JOSTPAY SCI

Loading the sci into an iframe is demonstrated below:
	style='width:100%;height:650px;border:1px solid #aaa;'

Example of JOSTPAY sci, loaded via an iframe

		<form method='post' action='//' >
			<input type='hidden' name='merchant' value='149' />
			<input type='hidden' name='amount' value='10000' />
			<input type='hidden' name='memo' value="Purchase of XYZ products" />
			<input type='hidden' name='ref' value="User:123-Product:ABC" />
			<input type='submit'  value="Pay Now" />

3.0 Transaction Confirmation

After a payment transaction (successful or unsuccessful), the following parameters will be posted back to your supplied notification_url via HTTP POST request .
	ref :the transaction reference 
	jostpay_id :the merchant's JOSTPAY ID
This section describes how to programatically validate/check a transaction status on JOSTPAY server, using the transaction information posted to your notification URL

3.1 Getting transaction information

The following parameters can be sent, through HTTP GET or POST request to the URL:

Input Field Name Description Example Value
action The value for this key must be get_transaction get_transaction
jostpay_id The receiver's JOSTPAY Id (this should be your JOSTPAY ID displayed on the API settings section) 149
ref Transaction reference User:123-Product:ABC
Optional Fields
amount If supplied, the value will be checked against the actual transaction amount, and an error will be returned if the values does not match 1000
Sample Codes for getting transaction information
			$my_jostpay_id=149; //this should be replaced with your JOSTPAY Id
			if(empty($_POST['ref']))$msg="Transaction reference not supplied.";
					'amount'=>'1000',  //the amount that you are expecting (this is optional but important)

				$ch = curl_init();
				curl_setopt($ch, CURLOPT_URL, $api_url);
				curl_setopt($ch, CURLOPT_POST, true);
				curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
				curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
				$response = curl_exec($ch);
				$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
				if($response_code != 200)$response=curl_error($ch);

				if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
					if($json===null)$msg="INVALID RESPONSE: $response"; 
					elseif($json['status_msg']!='COMPLETED')$msg="Transaction Not Completed. STATUS: ".$json['status_msg'];
						//Transaction successfuly validated, further processing can proceed here
						$msg="Transaction Completed, amount: ".$json['amount'];			
			echo $msg;
Below is a sample successful process's response.
{"jostpay_id":"149","ref":"User:123-Product:ABC","amount":"4.12","currency_code":"NGN","memo":"Purchase of XYZ products","date_time":"2016-03-22 13:41","status":"0","status_msg":"PENDING","info":"Perfectmoney payment, pending confirmation."}
Below is a sample response to a failed process, a JSON Object
{"error":"Transaction record not found"}

4.0 CMS/E-Commerce Modules

5.0 Disclaimer

The Author [JOSTPAY Limited] accepts no responsibility for damages to persons, property or data incurred through the use or misuse of these API and scripts. To the maximum extent permitted by law, in no event shall the Author [JostPay Limited] be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use or inability to use this API, even if the Author has been advised of the possibility of such damages.
This product is supplied as-is, with no warranties express or implied. Use this documentation at your own risk.