Merchant Tools

Instant Payment Notifications (IPN)

Introduction

The IPN system will notify your server when you receive a payment. This is a easy and useful way to integrate our payments into your software to automate order completion, digital downloads, accounting, or whatever you can think up.
It is implemented by making a HTTP POST call over a https:// URL to a script or CGI program on your server.

IPN Setup

The first step is to go to your Merchant page and get your API Secret. The API Secret is used to verify that an IPN was really sent from our servers.

At the same time you can optionally set an IPN URL; this is the URL that will be called when sending you IPN notifications. You can also set an IPN URL in your Payment Widget that will be used instead of this one.

IPN Retries / Duplicate IPNs

If there is an error sending your server an IPN, we will retry up to 10 times. Because of this you are not guaranteed to receive every IPN (if all 10 tries fail) or that your server will receive them in order.
Your IPN handler must always check to see if a payment has already been handled before to avoid double-crediting users, etc. in the case of duplicate IPNs.

Authenticating IPNs

We use your API Secret as the HMAC shared secret key to generate an HMAC signature of the raw POST data. The HMAC signature is sent as a HTTP header called HMAC.
Here is what it would look like in PHP:
		$api_secret = ''; //Your Merchant API Secret
		
		if (!isset($_POST['ipn_mode']) || $_POST['ipn_mode'] != 'hmac') { 
			die('IPN Mode is not HMAC'); 
		} 
     
		if (!isset($_SERVER['HTTP_HMAC']) || empty($_SERVER['HTTP_HMAC'])) { 
        	die('No HMAC signature sent.'); 
		} 
     
		$request = file_get_contents('php://input'); 
		if ($request === FALSE || empty($request)) { 
        	die('Error reading POST data'); 
		} 
         
		$hmac = hash_hmac("sha512", $request, trim($api_secret)); 
		if ($hmac != $_SERVER['HTTP_HMAC']) { 
        	die('HMAC signature does not match'); 
		} 

		// HMAC Signature verified at this point, load some variables. 
		$txn_id = $_POST['tx_id']; // Tx Id from Bitcoin Network
		$amount_f = floatval($_POST['amount_f']);  //Fiat Amount
		$amount_c = floatval($_POST['amount_c']);  //Crypto Amount
		$currency_symbol = $_POST['currency_symbol']; //Fiat Symbol
		$coin_symbol = $_POST['coin_symbol']; //Crypto Symbol
		$status = intval($_POST['status']); 
		$status_text = $_POST['status_text']; 
		$order_id = $_POST['order_id'];  
		$invoice_id = $_POST['invoice_id']; 
	
	//Compare the Ipn Values with the ones you saved on Database when generated the order_id if all is ok proceed
	if ($status == 2) { 
		if($_POST['received_confirms'] >= 2) {
			//Save data/status on your Database
			die('IPN OK'); // With the message LivePay knows all is ok and will not send more callbacks with this order_id		
			}
	}

	//Else

	die('IPN ERROR: Custom Message'); //A check got wrong.

Payment Status

Payments will post with a 'status' field, here are the currently defined values:
  • 1 = Waiting for buyer funds
  • 2 = We have confirmed coin reception from the buyer
To avoid IPN network congestion we have enabled Partial Payment checks on our Gateway:
  • A REST call to https://gw17.livepay.io/gw/merchantpartials/?apikey=merchant_api_key will show you a json reply with all the merchant Partial Payments as follows
    • [{"order_id":"84crsy2DpCd1","coin_symbol":"BTC","partial":"1","amount":"0.00025477","expected_amount":"0.00382925","left_amount":"-0.00357448"},
{"order_id":"ULQGvgmh4dHK","coin_symbol":"BTC","partial":"1","amount":"0.00165721","expected_amount":"0.00248801","left_amount":"-0.00083080"},
{"order_id":"R7jVAo3lHJqf","coin_symbol":"BTC","partial":"1","amount":"0.00016423","expected_amount":"0.00250424","left_amount":"-0.00234001"}]
  • You can use this information to alert your member that there is a left amount to finish the payment, always save the order_id on your database when generate a payment widget.
  • You can also process this payments manually from your LivePay dashboard

Code Samples

A complete example of an IPN Handler can be found in: [PHP].

IPN POST Fields

Field Name Description Required?
Required Fields
These fields will be here for all IPN types.
ipn_mode Currently: 'hmac' Yes
Deposit Information
tx_id The coin transaction ID of the payment. Yes
status Numeric status of the payment, IMPORTANT: You should never ship/release your product until the status is >= 2 Yes
status_text A text string describing the status of the payment. (useful for displaying in order comments) Yes
amount_c The total amount of the payment in cryptocurrenc Yes
coin_symbol The code of the crypto currency (BTC, LTC, ETH, etc.) Make sure to check this for accuracy for security in your IPN handler! Yes
currency_symbol The code of the fiat currency (USD, EUR, etc.) Make sure to check this for accuracy for security in your IPN handler! Yes
amount_f The total amount of the payment in the fiat currency you selected. Yes
received_confirms The number of confirms the payment has. Yes
invoice_id Relation code you genarate to identify the payment on your system. (You send us this code to identify the payment on your database). Yes
order_id Unique Id generated by our system to identify the payment (You can use the order id to generate a payment widget). Yes