1.0 Developers' API Introduction


This document describes how to programatically transfer funds, and/or receive payments on your website, using UnifiedPurse (You must have created a UnifiedPurse 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 UnifiedPurse, Click here to generate your payment url or snippet/script to be shared or included in your applications and start recieving payments worldwide.

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 
		unifiedpurse_transaction_reference :the internal transaction reference on UnifiedPurse	
This section describes how to programatically validate/check a transaction status on UnifiedPurse 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://unifiedpurse.com/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 mycompany
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://unifiedpurse.com/api_v1?action=get_transaction&receiver=mycompany&ref=User%3A123-Product%3AABC&trade_id=0
	<?php

		$my_username='mycompany'; //this should be replaced with your UnifiedPurse username or email

		if(empty($_POST['ref']))$msg="Transaction reference not supplied.";
		else
		{
			$ref=$_POST['ref'];
			//$ext_txn_ref=$_POST['unifiedpurse_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://unifiedpurse.com/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": "mycompany",
		"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 NGN",
		"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": "unifiedpurse",
		"blockchain_txid": "",
		"original_amount": 2000,
		"original_currency_code": "NGN",
		"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"=>"Guaranty Trust Bank",
                "country_code"=>"NG",
            },
            "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.3 Releasing Escrow Transaction

The following parameters can be sent, through HTTP GET or POST request to the URL: https://unifiedpurse.com/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 UnifiedPurse [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 relesing escrow
https://unifiedpurse.com/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://unifiedpurse.com/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.
{"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://unifiedpurse.com/transaction?receipt={receiver_username}::{receiver_ref}
(e.g if the receiver username is: unifiedpurse, and custom reference is: ProductXYZ123, then transaction receipt is also accessible from https://unifiedpurse.com/transaction?receipt=unifiedpurse::ProductXYZ123)

3.3 UnfiedPurse Transaction Widget

Monitor and perform actions on your transaction history by loading the widget url //unifiedpurse.com/transaction-widget/{USERNAME}/{TOKEN}/{TOKEN_KEY} with the following parameters in an iframe, on your secured (private) webpage

Widget Url Parameter Description Example Value
{USERNAME} Your username OR user_id on UnifiedPurse mycompany
{TOKEN} A md5 hashing of sha512 hash generated from your account's username, widget-password, and token key in this pattern
md5(username+password+token_key)
+ here means concatenation of of values, not to include the + sign
password here is widget password from account security. Not your main password
3d51f06ca4a6454f4480113191e24e84
{TOKEN_KEY} A very random string; preferrably the unix timestamp or payer's email (the records in this case, will be limited to only this payer.) 1502910803
Sample snippet for loading transaction history widget in an iframe
<iframe
		src='//unifiedpurse.com/transaction-widget/mycompany/3d51f06ca4a6454f4480113191e24e84/1502910803' 
		style='width:100%;height:560px;border:1px solid #bbb;'
	></iframe>
	<?php

		$account_username='mycompany';
		$widget_pass='password';
		$token_key=time();
		$token=md5($account_username.$widget_pass.$token_key);

		$widget_url="//unifiedpurse.com/transaction-widget/$account_username/$token/$token_key";
	?>
	<iframe
		src='<?php echo $widget_url; ?>' 
		style='width:100%;height:560px;border:1px solid #bbb;'
	></iframe>
			

4.0 Updating Payment Option


For Bitcoin, Tether, TetherTRC20, Litecoin, Ethereum payment options, you are allowed to remotely change your receiving address.
The following parameters can be sent, through HTTP GET or POST request to the URL: https://unifiedpurse.com/api_v1

Input Field Name Description Example Value
action The value for this key must be update_payment_option update_payment_option
email Your email address on UnifiedPurse [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
payment_option_id The ID of this payment option, as displayed on your dashboard 21
new_address The new receiving wallet address that should be. 1DQkKM7qt7aLkF1a5FAv2DP2CQMedGfpTv
Sample Codes for getting your relesing escrow
https://unifiedpurse.com/api_v1?action=update_payment_option&email=sample%40gmail.com&token_key=1502910803&token=3d51f06ca4a6454f4480113191e24e84&payment_option_id=25&new_address=1DQkKM7qt7aLkF1a5FAv2DP2CQMedGfpTv
	<?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'=>'update_payment_option',
			'email'=>$account_email,
			'token_key'=>$token_key,
			'token'=>$token,
			'payment_option_id'=>'25',
			'new_address'=>'1DQkKM7qt7aLkF1a5FAv2DP2CQMedGfpTv'
		);
		
		$api_url='https://unifiedpurse.com/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'])){
				//Receiving bitcoin address updated from ... to 1DQkKM7qt7aLkF1a5FAv2DP2CQMedGfpTv
				$msg=$json['success']['msg'];			
			}
		}
		
		echo $msg;
	?>
	
Below is a sample successful process's response.
{"success":{"msg":"Receiving bitcoin address updated from ... to 1DQkKM7qt7aLkF1a5FAv2DP2CQMedGfpTv"}}
Below is a sample response to a failed process, a JSON Object
{"error":"You can not set receiving address for payment option 'paypal'. Only allowed for: bitcoin, litecoin, ethereum, tether, tethertrc20"}

5.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.