Guides
Start typing to search…

Payment Status Notification

Merchant Webhook or the 3-endpoints

📘

WARNING: Please note that multiple payment notifications (either from return URL, Notification URL or callback URL) for a single transaction is possible but this does not mean that the buyer has paid twice or multiple times. Additionally, if the domain used for these URLs differs from the company's website domain, it must be registered to ensure proper transaction handling.

Return URL with IPN (Instant Payment Notification)

For normal payment flow, the buyer browser is being redirected to a hosted payment page, financial institution or channel page(if any), and then returned to the merchant website or system. Users might close the browser any time throughout the payment process, even if the payment is completed, successfully or failed. Another possible reason that rarely happens is the network connectivity issue. As a result, the payment gateway is unable to update the merchant system on the payment status. Therefore, merchants are recommended to implement IPN to acknowledge(ACK) upon the receiving of status from gateway. Otherwise the callback worker will resend the payment status within a time interval.Implementation:Step 1: Login to the merchant portal, and go to tab Transactions -> Settings, fill in the Return URL, which must be starting with https. Return URL with IPN can be activated for better merchant-payment system communication. Check the checkbox beside “Enable Instant Payment Notification (IPN)”, as shown below:Step 2: There are 2 approaches to ack on receiving payment status.

  1. Simple front-end snippet: copy the Javascript (JS) code from merchant admin and paste it on the merchant receipt page (which shows payment success/failed), preferable in the HTML header, before </head> tag.
  2. Advanced back-end scripting: merchant is to echo back all the POST variables with one additional variable, i.e. “treq” with value 1. PHP sample code is provided below.URL: https://pay.fiuu.com/RMS/API/chkstat/returnipn.php

Step 3: Merchant to prepare a Notification URL and Callback URL script, which is similar to return URL script but serves at the backend, in order to receive consequent payment notification in case the merchant system misses the first notification attempt from the payment gateway.

Example of back-end IPN script for PHP (combined with return URL script)

<?php

$sec_key ="xxxxxxxxxx"; //Replace xxxxxxxxxx with Secret_Key

$_POST[treq]    =	1; // Additional parameter for IPN

// Value always 1. Do not change this value.
$tranID 	=	$_POST['tranID'];
$orderid 	=	$_POST['orderid'];
$status 	=	$_POST['status'];
$domain 	=	$_POST['domain'];
$amount 	=	$_POST['amount'];
$currency 	=	$_POST['currency'];
$appcode 	=	$_POST['appcode'];
$paydate 	                  =	$_POST['paydate'];
$skey 	                  =	$_POST['skey'];

/***********************************************************
* Snippet code in purple color is the enhancement required
* by merchant to add into their return script in order to
* implement backend acknowledge method for IPN
************************************************************/
while ( list($k,$v) = each($_POST) ) {
  $postData[]= $k."=".$v;
}
$postdata	= implode("&",$postData);
$url 		= "https://pay.fiuu.com/RMS/API/chkstat/returnipn.php";
$ch 		= curl_init();
curl_setopt($ch, CURLOPT_POST		, 1 	   );
curl_setopt($ch, CURLOPT_POSTFIELDS	, $postdata );
curl_setopt($ch, CURLOPT_URL		, $url            );
curl_setopt($ch, CURLOPT_HEADER	                  , 1                 );
curl_setopt($ch, CURLINFO_HEADER_OUT              , TRUE	   );
curl_setopt($ch, CURLOPT_RETURNTRANSFER 	, 1 	   );
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER 	, FALSE       );
curl_setopt($ch, CURLOPT_SSLVERSION                  , 6               );  // use only TLSv1.2
$result = curl_exec( $ch );
curl_close( $ch );

/***********************************************************
* To verify the data integrity sending by PG
************************************************************/
$key0 = md5( $tranID.$orderid.$status.$domain.$amount.$currency );
$key1 = md5( $paydate.$domain.$key0.$appcode.$sec_key );
if( $skey != $key1 ) $status= -1; // Invalid transaction
if ( $status == "00" ) {
  if ( check_cart_amt($orderid, $amount) ) {
    // write your script here .....
  }
} else {
  // failure action
}

?>

Notification URL with IPN

Direct payment status notification is a back-end instant update mechanism that sends over the payment status notification from gateway directly to the merchant server or system, without relying on any user agent such as web browser or mobile application.

Notification URL script is similar to return URL script but no output is required for front-end user interface. This is also known as background URL.

Implementation:

Step 1: Login to merchant portal and go to tab Transactions -> Settings, fill in the Notification URL, which must be starting with https. Notification URL with IPN can be activated for better merchant-payment system communication. Check the checkbox beside “Enable Instant Payment Notification (IPN)”, as shown below:


Step 2: Merchant to prepare a Notification URL script, which is similar to return URL script.

Step 3: If IPN is disabled please ignore this step. Merchants have to echo back all the POST variables with one additional variable, i.e. “treq” with value 1. PHP sample code is provided below.URL: https://pay.fiuu.com/RMS/API/chkstat/returnipn.php


Notification Parameters (via POST method)

Note: Values are not URL encoded


Example of Notification URL with IPN script for PHP

<?php

$sec_key ="xxxxxxxxxx"; //Replace xxxxxxxxxx with Secret_Key

$_POST[treq]    =	1; // Additional parameter for IPN. Value always set to 1. 

/********************************
*Don't change below parameters
********************************/
$nbcb 	        =	$_POST['nbcb'];
$tranID 	=	$_POST['tranID'];
$orderid 	=	$_POST['orderid'];
$status 	=	$_POST['status'];
$domain 	=	$_POST['domain'];
$amount 	=	$_POST['amount'];
$currency 	=	$_POST['currency'];
$appcode 	=	$_POST['appcode'];
$paydate 	                  =	$_POST['paydate'];
$skey 	                  =	$_POST['skey'];
 
/***********************************************************
* Snippet code in purple color is the enhancement required
* by merchant to add into their notification script in order to
* implement backend acknowledge method for IPN
************************************************************/
while ( list($k,$v) = each($_POST) ) {
  $postData[]= $k."=".$v;
}
$postdata	= implode("&",$postData);
$url 		= "https://pay.fiuu.com/RMS/API/chkstat/returnipn.php";
$ch 		= curl_init();
curl_setopt($ch, CURLOPT_POST			, 1         );
curl_setopt($ch, CURLOPT_POSTFIELDS		, $postdata );
curl_setopt($ch, CURLOPT_URL			, $url    );
curl_setopt($ch, CURLOPT_HEADER		                  , 1         );
curl_setopt($ch, CURLINFO_HEADER_OUT                                 , TRUE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER 	                  , 1         );
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER 	                  , FALSE);
curl_setopt($ch, CURLOPT_SSLVERSION                                    , 6         );  // use only TLSv1.2
$result = curl_exec( $ch );
curl_close( $ch );

/***********************************************************
* To verify the data integrity sending by PG
************************************************************/
$key0 = md5( $tranID.$orderid.$status.$domain.$amount.$currency );
$key1 = md5( $paydate.$domain.$key0.$appcode.$sec_key );
if( $skey != $key1 ) $status= -1; // Invalid transaction
if ( $status == "00" ) {
  if ( check_cart_amt($orderid, $amount) ) {
    // write your script here .....
  }
} else {
  // failure action
}

?>

Callback URL with IPN

Callback mechanism is a back-end activity that is initiated by payment gateway to notification the merchant system once there are changes on any payment status.

Callback URL script is similar to return URL script. Both handle the payment status result; Unlike the return URL script, callback URL script is to handle defer status update or all other non-realtime payment status updates, such as Fiuu Cash payment.

Merchant must fill the Callback URL which must be starting with https in merchant portal in order to get those non-realtime status update from the gateway. Callback URL IPN can be activated for better merchant-payment system communication. Instead of returning all parameters from the gateway, merchant’s callback script just need to echo “CBTOKEN:MPSTATOK”, in plaintext, without double quotes or any HTML tags.

Merchant can actually use the same script for both callback URL & return URL, because there is only one extra parameter in callback request, in addition to return URL parameters, which is “nbcb”. Besides, an additional status code, 22 has been introduced for “pending” transaction status.

Once there is a status changed event, payment gateway will POST the following parameters to merchant callback URL. If the payment gateway could not get the actual ACK message from the merchant, it will retry for a maximum 3 times, of 15 minutes interval for each attempt.

Callback Parameters (via POST method)

Note: Values are not URL encoded


Example of callback URL script for PHP

<?php

$sec_key ="xxxxxxxxxx"; //Replace xxxxxxxxxx with Secret_Key

$nbcb 	        =	$_POST['nbcb'];
$tranID 	=	$_POST['tranID'];
$orderid 	=	$_POST['orderid'];
$status 	=	$_POST['status'];
$domain 	=	$_POST['domain'];
$amount 	=	$_POST['amount'];
$currency 	=	$_POST['currency'];
$appcode 	=	$_POST['appcode'];
$paydate 	=	$_POST['paydate'];
$skey 	        =	$_POST['skey'];

/***********************************************************
* To verify the data integrity sending by PG
************************************************************/
$key0 = md5( $tranID.$orderid.$status.$domain.$amount.$currency );
$key1 = md5( $paydate.$domain.$key0.$appcode.$sec_key );
if( $skey != $key1 ) $status= -1; // Invalid transaction

if ( $status == "00" ) {
  if ( check_cart_amt($orderid, $amount) ) {
    // write your script here .....
  }
} else {
  // failure action
  // write your script here .....
}

if ( $nbcb==1 ) {
  //callback IPN feedback to notified PG
  echo “CBTOKEN:MPSTATOK”; exit;
}else{
  //normal IPN and redirection
}
?>

Value of “channel” in notification and callback URL



Note: Channel in yellow text means the channel had been obsoleted

Updated 11 days ago