Developers API

1.0 Developers' API Introduction

This document describes how to programatically transfer funds, and/or receive payments on your website, using Zitopay (You must have Created a Zitopay Account before using this tool. .

2.0 Shopping Cart Interface

To accept online payments on you website, online-stores, mobile/desktop app or phisically for your products and services using Zitopay, Click here to generate your payment url or snippet/script to be shared or included in your Website/applications and start recieving payments from Cameroon.

3.0 Transaction Confirmation

After a successful payment transaction, the following parameters will be posted back to your supplied notification_url via HTTP POST request .
		ref :the transaction reference 
		zitopay_transaction_reference :the internal transaction reference on Zitopay
This section describes how to programatically validate/check a transaction status on Zitopay 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: https://zitopay.africa/api_v1

Input Field Name Description Example Value
action The value for this key must be get_transaction get_transaction
receiver The receiver's username or email [email protected]
ref Transaction reference User:123-Product:ABC
Optional Fields
amount If supplied, the value will be checked against the original transaction amount supplied on the payment request, and an error will be returned if the values does not match 0.053
currency If supplied, the value will be checked against the original transaction currency supplied on the payment request, and an error will be returned if the values does not match BTC
trade_id Since it is possible to also specify a ref during trades, this value is important to check and ensure that a user isn't trying to use ref from a trade transaction to validate a payment transaction. In short, for a payment transaction, this value will be zero. 0
Sample Codes for getting transaction information
https://zitopay.africa/api_v1?action=get_transaction&receiver=sample%40gmail.com&ref=User%3A123-Product%3AABC&trade_id=0 
	<?php

		$my_username='[email protected]'; //this should be replaced with your Zitopay username or email

		if(empty($_POST['ref']))$msg="Transaction reference not supplied.";
		else
		{
			$ref=$_POST['ref'];
			//$ext_txn_ref=$_POST['zitopay_transaction_reference'];
		
			$post_data=array(
				'action'=>'get_transaction',
				'receiver'=>$my_username,
				'ref'=>$ref,
				'trade_id'=>0,
				//'amount'=>'0.1',  //the amount that you are expecting (this is optional)
				//'currency'=>'BTC',  //the currency that you are expecting (this is optional)
			);
			
			$api_url='https://zitopay.africa/api_v1';

			$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);
			//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //only uncomment if you do not have SSL, not-recomended
			
			$response = curl_exec($ch);
			$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
			if($response_code != 200)$response=curl_error($ch);
			curl_close($ch);

			if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
			else
			{
				$json=@json_decode($response,true);
				
				if($json===null)$msg="INVALID RESPONSE: $response"; 
				elseif(!empty($json['error']))$msg=$json['error'];
				elseif($json['status_msg']!='COMPLETED')$msg="Transaction Not Completed. STATUS: ".$json['status_msg'];
				else
				{
					//Transaction successfully validated, further processing can proceed here
					$msg="Transaction Completed, amount: ".$json['amount'];			
				}
			}
		}
		
		echo $msg;
	?>
Below is a sample successful process's response (NOTE: This does not mean a successful transaction, check the transaction status) 
	{
		"username": "[email protected]",
		"email": "[email protected]",
		"ref": "User:123-Product:ABC",
		"trade_id": 0,
		"currency_code": "BTC",
		"amount": 0.00106,
		"commission_for_receiver": 0,
		"total_received": 0.00106,
		"memo": "Buying Product ABC With 2000.00 XAF",
		"date_time": "2018-04-12T13:17:10 BST",
		"status": 1,
		"status_msg": "COMPLETED",
        "probation_successful": 1,
        "probation_until": "2018-04-12T16:17:10 BST",
		"type": "TRANSFER",
		"payment_method": "bitcoin",
		"blockchain_txid": "",
		"original_amount": 2000,
		"original_currency_code": "XAF",
		"info": "",
		"meta_info":{}
	}
For transactions that are success but still under probation (i.e the imported payment gateways with charge-backs/reversal tendencies). The value of probation_successful should also be 1 for it to be considered final.
meta_info may contain additional information, depending on the payment mode used.
e.g here is typical meta_info for a payment made with credit card (through an imported-gateway), in which the receiver pre-required KYC verification of the payer. 
    "meta_info":{
            "payment_meta_info":{
                "last4"=>1234,
                "exp_month"=>"09"
                "exp_year"=>"2022",
                "card_type"=>"debit-Mastercard",
                "bank"=>"UBA Bank",
                "country_code"=>"CM",
            },
            "kyc_info":{
                "credit_card_last_digits":"1236",
                "credit_card_admin_comment":"documents verified"
                "id_validation_expiry":"1593801223",
                "card_validation_expiry":"1664492400",
                "card_expiry_month":"09",
                "card_epiry_year":"2022"
            }          
        }
Below is a sample response to a failed process, a JSON Object 
{"error":"Transaction record not found"}

3.2 Balance Enquiry

The following parameters can be sent, through HTTP GET or POST request to the URL: https://zitopay.africa/api_v1

Input Field Name Description Example Value
action The value for this key must be get_balance get_balance
email Your email address on Zitopay [email protected]
token A md5 hashing of sha512 hash generated from your account's password, email, and token key in this pattern
md5(sha512(password+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		3d51f06ca4a6454f4480113191e24e84
token_key A very random string; preferrably the unix timestamp generated and used when making this request 1502910803
Optional Fields
currency If supplied, the only the ballance of the supplied currency will be returned. Currency can be any of XAF, BTC BTC
Sample Codes for getting your account balance
https://zitopay.africa/api_v1?action=get_balance&email=sample%40gmail.com&token_key=1502910803&token=3d51f06ca4a6454f4480113191e24e84 
	<?php

		$account_email='[email protected]';
		$account_pass='password';
		$token_key=time();
		$token=md5(hash('sha512',$account_pass.$account_email).$token_key);

		$post_data=array(
			'action'=>'get_transaction',
			'email'=>$account_email,
			'token_key'=>$token_key,
			'token'=>$token,
		);
		
		$api_url='https://zitopay.africa/api_v1';

		$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);
		//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //only uncomment if you do not have SSL, not-recomended	
		
		$response = curl_exec($ch);
		$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
		if($response_code != 200)$response=curl_error($ch);
		curl_close($ch);

		if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
		else
		{
			$json=@json_decode($response,true);
			
			if($json===null)$msg="INVALID RESPONSE: $response"; 
			elseif(!empty($json['error']))$msg=$json['error'];
			else
			{
				//Balance for each currency is now available under corresponding currency code
				$msg="Bitcoin balance: ".$json['BTC'];			
			}
		}
		
		echo $msg;
	?>
Below is a sample successful process's response. 
{"XAF":0,"BTC":0}
Below is a sample response to a failed process, a JSON Object 
{"error":"Invalid token"}

3.3 Releasing Escrow Transaction

The following parameters can be sent, through HTTP GET or POST request to the URL: https://zitopay.africa/api_v1

Input Field Name Description Example Value
action The value for this key must be release_escrow release_escrow
email Your email address on Zitopay [email protected]
token A md5 hashing of sha512 hash generated from your account's password, email, and token key in this pattern
md5(sha512(password+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		3d51f06ca4a6454f4480113191e24e84
token_key A very random string; preferrably the unix timestamp generated and used when making this request 1502910803
ref The transaction reference 15349519661068
Sample Codes for getting your account balance
https://zitopay.africa/api_v1?action=release_escrow&email=sample%40gmail.com&token_key=1502910803&token=3d51f06ca4a6454f4480113191e24e84&ref=15349519661068 
	<?php

		$account_email='[email protected]';
		$account_pass='password';
		$token_key=time();
		$token=md5(hash('sha512',$account_pass.$account_email).$token_key);

		$post_data=array(
			'action'=>'get_transaction',
			'email'=>$account_email,
			'token_key'=>$token_key,
			'token'=>$token,
			'ref'=>'15349519661068'
		);
		
		$api_url='https://zitopay.africa/api_v1';

		$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);
		//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //only uncomment if you do not have SSL, not-recomended	
		
		$response = curl_exec($ch);
		$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
		if($response_code != 200)$response=curl_error($ch);
		curl_close($ch);

		if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
		else
		{
			$json=@json_decode($response,true);
			
			if($json===null)$msg="INVALID RESPONSE: $response"; 
			elseif(!empty($json['error']))$msg=$json['error'];
			elseif(!empty($json['success']))
			{
				//Escrow succesfully released
				$msg=$json['success']['msg'];			
			}
		}
		
		echo $msg;
	?>
Below is a sample successful process's response. 
{"XAF":0,"BTC":0}
Below is a sample response to a failed process, a JSON Object 
{"error":"Invalid token"}
Meanwhile, the transaction receipt page can also be accessed directly with
https://zitopay.africa/transaction?receipt={receiver_username}::{receiver_ref}
(e.g if the receiver username is: zitopay, and custom reference is: ProductXYZ123, then transaction receipt is also accessible from https://zitopay.africa/transaction?receipt=zitopay::ProductXYZ123)

4.0 Transfer funds

The four types of funds sending actions basically follow the same pattern, they only differs in some request parameters and the extra details in the response

4.1 Transfer Funds

The following parameters can be sent, through HTTP GET or POST request to the URL: https://zitopay.africa/api_v1 in order to intiate a fund-transfer transaction

Input Field Name Description Example Value
action The value for this key must be transfer transfer
proceed The value for this key should be confirm. If otherwise, the transaction will not actually be commited, you will only see the preview information and be sure that this transaction would have gone through successfully confirm
email Your email address on Zitopay [email protected]
token A md5 hashing of sha512 hash generated from your account's password, email, and token key in this pattern
md5(sha512(password+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		3d51f06ca4a6454f4480113191e24e84
transaction_pin_hash A md5 hashing of md5 hash generated from your account's transaction pin, email, and token key in this pattern
md5(md5(transaction_pin+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		42edb714dd02540466591fe6edf154fd
token_key A very random string; preferrably the unix timestamp generated and used when making this request 1502910803
payment_currency The wallet to transfer this fund from; as long as you have sufficient balance in that wallet. Presently the value can be any of XAF, BTC BTC
amount The numerical amount to be transferred, depending on the specified wallet's currency 1000
recipient This can either be the registered email or username of the receiver at Zitopay
CAUTION: Double-check to make sure to avoid transferring into a wrong account 		[email protected]
Optional Fields
escrow 0 and 1 are the values that are allowed here;
If you supply '1', then the fund will not be released to the receiver until you approve.
Supplying '0' has no effect, it's the default, and means that the fund should be released immediately 		0
receiver_bear_charges 0 and 1 are the values that are allowed here;
If you supply '1', then the transfer fee will be deducted from the amount that you supplied. 		0
auto_approval_date A valid date (such as 2017-04-01 14:30) UIf supplied, the fund will only be realeased to the receiver on or after the date. 0
ref Your custom transaction reference Invoice:123-Product:ABC
Sample Codes for transferring funds to another user's account
https://zitopay.africa/api_v1?action=transfer&proceed=confirm&payment_currency=USD&recipient=b%40c.com&amount=1000&escrow=0&ref=User%3A123-Product%3AABC&email=sample%40gmail.com&token_key=1502910803&token=3d51f06ca4a6454f4480113191e24e84&transaction_pin_hash=42edb714dd02540466591fe6edf154fd 
	<?php

		$recipient_email=$_POST['recipient'];
		
		$account_email='[email protected]';
		$account_pass='password';
		$transaction_pin='123456';
		$token_key=time();
		$token=md5(hash('sha512',$account_pass.$account_email).$token_key);
		$transaction_pin_hash=md5(md5($transaction_pin.$account_email).$token_key);
		

		$post_data=array(
			'action'=>'transfer',
			'proceed'=>'confirm',
			'payment_currency'=>'USD',
			'recipient'=>$recipient_email,
			'amount'=>'1000',
			'escrow'=>0,
			'ref'=>$ref,
			'email'=>$account_email,
			'token_key'=>$token_key,
			'token'=>$token,
			'transaction_pin_hash'=>$transaction_pin_hash,
		);
		
		$api_url='https://zitopay.africa/api_v1';

		$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);
		//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //only uncomment if you do not have SSL, not-recomended	
		
		$response = curl_exec($ch);
		$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
		if($response_code != 200)$response=curl_error($ch);
		curl_close($ch);

		if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
		else
		{
			$json=@json_decode($response,true);
			
			if($json===null)$msg="INVALID RESPONSE: $response"; 
			elseif(!empty($json['error']))$msg=$json['error'];
			else
			{
				//Transaction successfully processed, further processing can proceed here
				$msg=$json['success'];
				$temp=print_r($json['transaction'],true);
			}
		}
		
		echo $msg;
	?>
Below is a sample successful process's response. 
{"success":"Transaction Successful Reference: 1492486939","transaction":{"transaction_id":"24","date_time":"2017-04-18 04:42:19","user_id":"1","related":"0","amount":"0.1","site_charges":"5.01","type":"2","currency_code":"BTC","original_currency_code":"BTC","status":"1","payment_method":"transfer","transaction_reference":"1492486939","batch_used":"","details":"Transferring 0.1 BTC","json_details":{"percentage_commission":0.5,"fixed_commission":5,"percentage_commission_amount":0.0005,"preview_info":{"Sender's Details":{"Sender's Name":"firstname lastname","Sender's Email":"[email protected]","Sender's Phone":"+2348000000000","Sender's Country":"Nigeria"},"Receiver's Details":{"Name":"firstname lastname","Country":"Nigeria","Escrow Transaction":"NO"},"Summary":{"Amount":"0.1 BTC","Fixed Charges":"5 BTC","Transfer Commission":"0.0005 BTC (0.5 %)","Total Amount":"5.11 BTC"}}},"json_info":null,"time":"1492486939","escrow_status":"0","related_user_id":"2","ref":"","to_amount":"0.1","to_currency_code":"BTC","firstname":"firstname","lastname":"lastname","email":"[email protected]","phone":"+3311111111"}}
Below is a sample response to a failed process, a JSON Object 
{"error":"Invalid account credentials"}

4.2 Withdraw Funds

The following parameters can be sent, through HTTP GET or POST request to the URL: https://zitopay.africa/api_v1 in order to intiate a fund withdrawal transaction

Input Field Name Description Example Value
action The value for this key must be withdraw withdraw
proceed The value for this key should be confirm. If otherwise, the transaction will not actually be commited, you will only see the preview information and be sure that this transaction would have gone through successfully confirm
email Your email address on Zitopay [email protected]
token A md5 hashing of sha512 hash generated from your account's password, email, and token key in this pattern
md5(sha512(password+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		3d51f06ca4a6454f4480113191e24e84
transaction_pin_hash A md5 hashing of md5 hash generated from your account's transaction pin, email, and token key in this pattern
md5(md5(transaction_pin+email)+token_key)
+ here means concatenation of of values, not to include the + sign 		42edb714dd02540466591fe6edf154fd
token_key A very random string; preferrably the unix timestamp generated and used when making this request 1502910803
payment_currency The wallet to transfer this fund from; as long as you have sufficient balance in that wallet. Presently the value can be any of XAF, BTC BTC
amount The numerical amount to be transferred, depending on the specified wallet's currency 1000
Optional Fields
Your specified payment currency will determine if you should supply 'destination_account' or bank details. If you are withdrawing e-currencies, you will need to rather supply 'destination_account'
destination_account e.g If the payment_currency is BTC, the destination_account should be the bitcoin address 1PyTX2UzWuxNu3dywPdrJa1SE2dTcUKfqf
ref Your custom transaction reference Invoice:123-Product:ABC
notification_url When a transaction has been succesfuly completed, the transaction reference (under an HTTP POST key 'ref') will be posted to this url http://example.com/payment/withdrawal_completed_notification
Sample Codes for withdrawing funds easily
https://zitopay.africa/api_v1?action=withdraw&proceed=confirm&payment_currency=BTC&email=sample%40gmail.com&token_key=1502910803&token=3d51f06ca4a6454f4480113191e24e84&transaction_pin_hash=42edb714dd02540466591fe6edf154fd&amount=1000&destination_account=1PyTX2UzWuxNu3dywPdrJa1SE2dTcUKfqf&ref=User%3A123-Product%3AABC 
	<?php

		$account_email='[email protected]';
		$account_pass='password';
		$transaction_pin='123456';
		$token_key=time();
		$token=md5(hash('sha512',$account_pass.$account_email).$token_key);
		$transaction_pin_hash=md5(md5($transaction_pin.$account_email).$token_key);

		$post_data=array(
			'action'=>'withdraw',
			'proceed'=>'confirm',
			'payment_currency'=>'USD',
			'email'=>$account_email,
			'token_key'=>$token_key,
			'token'=>$token,
			'transaction_pin_hash'=>$transaction_pin_hash,
			'amount'=>'1000',
			'destination_account'=>'1PyTX2UzWuxNu3dywPdrJa1SE2dTcUKfqf',
			'ref'=>$ref,
		);
		
		$api_url='https://zitopay.africa/api_v1';

		$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);
		//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //only uncomment if you do not have SSL, not-recomended	
		
		$response = curl_exec($ch);
		$response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
		if($response_code != 200)$response=curl_error($ch);
		curl_close($ch);

		if($response_code != 200)$msg="HTTP ERROR $response_code: $response";
		else
		{
			$json=@json_decode($response,true);
			
			if($json===null)$msg="INVALID RESPONSE: $response"; 
			elseif(!empty($json['error']))$msg=$json['error'];
			else
			{
				//Transaction successfully processed, further processing can proceed here
				$msg=$json['success'];
				$temp=print_r($json['transaction'],true);
			}
		}

		echo $msg;
	?>

6.0 Disclaimer

The Author 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 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.
circle
circle

Start Accepting Payments Today