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