Introduction
The Instant Payment Notifications system will send POST data to your website when you receive a payment to your callback address or invoice and when the payment status is changed: pending, complete.
Your application must return response 200 status otherwise, it retries 9 more times every 5 minutes.
IPN Verification
To verify that an IPN is sent from AnonWallet, you must set an IPN Secret that can be a secret word chosen by you.
The IPN Secret can be set up in the Account -> Security -> Configure IPN
Your IPN Secret is used to generate an HMAC signature of the internal transaction-id and your IPN Secret.
You can verify the received HMAC signature with the below function code:
hash_hmac("sha512", $_POST['internal_txId'], $ipn_secret)
IP Address Whitelist
We recommend whitelisting our server IPs from where the IPN is sent. Regularly check those IPs, they can be updated anytime.
162.0.235.233
162.0.235.235
IPN POST Fields
| Name | Value |
|---|---|
| status | 1 - Pending Payment (Detected in the blockchain) 2 - Complete Payment (Received and allocated to your account) 3 - Underpaid Payment (The amount received is less than the invoice amount requested) 4 - Overpaid Payment (The amount received is higher than the invoice amount requested, it can be considered as a complete payment) |
| internal_txId | ID of the transaction from AnonWallet system |
| txId | The TX ID (Transaction ID) from the blockchain |
| address | The address where the payment was received |
| coin_abbreviation | The abbreviation of the cryptocurrency the payment was made for (example: BTC, LTC, DOGE) |
| coin_name | The cryptocurrency name the payment was made for (example: Bitcoin, Litecoin, Dogecoin) |
| net_amount | The amount that is credited to the merchant account after subtracting the processing fee |
| payment_amount | The amount paid by the shopper to the callback address |
| fee_deducted | The fee deducted by AnonWallet |
| label | The address label if you have one set up, if not, NULL is returned |
| auto_forward | TRUE if the callback address has an auto-forward address set up, FALSE if not |
| forward_address | The forwarded address set by you, if not set up, NULL is returned |
| hmac | The hmac signature formatted from the internal_txId and merchant ipn_secret |
| *invoice_amount | The amount specified on the invoice when it was created (Recommended to check if matches with the payment_amount received on the callback address) |
| *invoice_id | The external ID specified by merchant when the invoice was created |
** invoice_amount, invoice_id
Invoice POST fields are sent with the IPN if create_invoice method was used
Code Example
<?php
//Fill it with your ipn secret set up on your AnonWallet.Net account
$ipn_secret = '';
$request_ip = $_SERVER['REMOTE_ADDR'];
$allowed_ips = [162.0.235.233, 162.0.235.235];
//Verify the IP from who comes the post request
if(!in_array($request_ip, $allowed_ips)) {
die('Request IP is not allowed');
}
if(!isset($_POST['hmac'])) {
die('No HMAC signature sent');
}
$received_hmac = $_POST['hmac'];
//Generate hmac signature
$hmac = hash_hmac("sha512", $_POST['internal_txId'], $ipn_secret);
//Verify the hash signature match (PHP 5.6.0 or above)
if(!hash_equals($hmac, $received_hmac)) {
errorAndDie('HMAC signature does not match');
}
$status = $_POST['status'];
$internal_txId = $_POST['internal_txId'];
$txId = $_POST['txId'];
$address = $_POST['address'];
$coin_abbr = $_POST['coin_abbreviation'];
$coin_name = $_POST['coin_name'];
$net_amount = $_POST['net_amount'];
$payment_amount = $_POST['payment_amount'];
$fee_deducted = $_POST['fee_deducted'];
$label = $_POST['label'];
$auto_forward = $_POST['auto_forward'];
$forward_address = $_POST['forward_address'];
if($status == 2 || $status == 4) {
//Payment is complete, you can process it in your system
} else {
//Payment is received, waiting for confirmations
}
die('IPN received OK');