Skip to main content

Callback

Introduction to Callback​

Once your Nochex Payment Page is up and running you may wish to add further integration between Nochex and your website. With Callback this is possible; this allows you to integrate your Nochex payments with your back-end operations. So you will get immediate confirmation and authentication of the Nochex payments you receive.

Using Callback offers a wide range of extra functionality, such as

  • Process your customers payments in real time
  • Give immediate feedback to your customers
  • Store your Nochex payments in your own database
  • Ideal for online products, such as website membership Callback can be integrated into the Nochex payment system so you don't have to log into the Nochex system to confirm that payments have been made.

Your customers will also benefit from Callback as they will get an immediate response to the order they have placed in addition to the Nochex transaction email.

What is Callback?​

Callback confirms and authenticates any payment that is made into your account by communicating with your server. To start using Callback you are first required to create a listener, the following information explains what a listener exactly is and how to implement one and contact Nochex Support to have this enabled on your Nochex account.

Callback Listener​

To detect and process Callback responses you will require a listener, this is script or code that will wait for a Callback response.

After your listener has received a response it is required to send the same information back to the Nochex server to confirm the details are matching. Once these checks have been made and you know the transaction has been successful you can carry out various actions such as:

  • Update order status e.g. Pending to Paid.
  • Update list of customer details
  • Enable customers to download media e.g. purchasing an eBook Your Callback listener can be written in any scripting language or programming language you choose, example code that could be used is included in this document.

To enable the Callback listener you will need to host it on your web server and enter the URL into the Callback URL field within the Payment Page Setup, for further details on how to achieve this follow the instructions below.

Creating a Listener​

You can write your Callback listener in any programming or scripting language you wish, however below is what functionality must be included when creating your Callback listener:

  1. Wait for an HTTP POST from the Nochex server.

  2. Once received, construct a HTTP POST to Nochex with all the form variables you received exactly as you received them. Your POST should be sent to: https://secure.nochex.com/callback/callback.aspx

  3. Wait for response from Nochex server either "AUTHORISED" or "DECLINED".

  4. If the response is "AUTHORISED", you need to do the following checks:

    • Check the "transaction_id" against the previous Nochex transaction you have processed to ensure it is not a duplicate.
    • Make sure the "to_email" is the email address registered in your Nochex account
    • Check that the amount, transaction date and other variables match the transaction on your website.
    • Once you have completed the above checks, you may update your database based on the information provided.

  5. After all checks have been carried out and you have confirmed they are valid details, carry out any further actions you wish.

  6. If you received a "DECLINED" notification, it should be treated as suspicious and investigated.

Setting up Call back URL/ Responder URL​

After you have logged in to your Nochex account, follow these instructions to setup your Call back URL:

  1. Click Payment Page Setup, from the Control Panel.
  2. Specify the URL for your listener in the Callback URL field.

You can also set up the call back URL within the HTML form POST to Nochex using the below parameter. Note: This will override the callback URL in your Nochex Control Panel

Parameter NameDescription
callback_urlThe URL that Nochex will send a notification to once a payment is made.

Form Example​

<form method="POST" action="https://secure.nochex.com/">
<input type="hidden" name="merchant_id" value="yourmerchantid">
<input type="hidden" name="amount" value="55.60">
<input type="hidden" name="callback_url"
value="http://yourwebsite.com/callbackhandler.php">
<input type="submit" value="Pay on Credit or Debit Card with Nochex"
</form>

Callback Step-by-Step​

How Callback works​

  1. A customer visits your website and decides to use Nochex to make a payment.

  2. The customer is then directed to the Nochex payment page where they enter their details and make a payment.

payment page

  1. After the customer has confirmed the payment, they are then directed to the Nochex confirmation page.

payment page confirmation

  1. Once the payment has been made, the Nochex server will post a confirmation to your callback listener. The confirmation includes the information about the transaction, such as the customer's address, the amount paid, transaction id, security key unique to that transaction.

  2. Once your server receives the confirmation, the callback listener should return all of the information posted to you to the Nochex callback authentication page including the unique security key to ensure it is the same transaction.

  3. The Nochex authentication page will then respond to your server with an "AUTHORISED" or "DECLINED" message.

  4. When your server receives the "AUTHORISED" response, you should check the details to make sure that the amount and email address match to those that were sent. However if a "DECLINED" response is received it should be treated as suspicious and investigated.

  5. Once you have checked all the relevant data you can update your database or carry out any other actions you wish and then continue with the purchase process.

Callback Diagram​

callback diagram

Legend:
red arrowThe red arrows show the customer's experience, they just see the immediate effects. They will see the updated webpage after Callback has been successful, if you have a success URL, this will be displayed.
blue arrowThe blue arrow shows the Callback token and what route it takes round the system.

Steps​

  1. A customer visits your website.

  2. Your customer decides to pay using Nochex, which you have integrated into your website.

  3. Once your customer has entered all their details they will be sent to the Nochex server to be checked.

  4. The details you received are then posted back to the Nochex server using your Callback listener.

  5. The Nochex server will then send a Callback response to your Callback listener page with either an "AUTHORISED" or "DECLINED" response; for the purpose of this diagram we assume it was the "AUTHORISED" response.

  6. You can implement various optional actions within your Callback listener, some of which include; sending an email with the Callback response to your email address and updating your database or records.

  7. After the optional actions and checking of details are complete you can then update your website, either to show a success URL or the current status of your customer's order.

Callback Variables​

VariableValueDescription
transaction_dateTransaction specificDate/time stamp of transaction.
transaction_idTransaction specificUnique code generated to distinguish transactions.
security_keyTransaction specificSystem generated key (for Nochex use).
amountTransaction specificAmount received into Nochex account after charges. (same as net amount)
gross_amountTransaction specificFull amount of the customers payment.
order_idTransaction specificTransaction specific code, order id as passed by you, the merchant. Your customer is not able to view or edit this. It must be unique per transaction.
merchant_idTransaction specificMerchant Alias of the payment recipient.
email_addressTransaction specificEmail address of the payment sender.
postageTransaction specificPostage amount for transaction.
insuranceTransaction specificInsurance amount for transaction.
optional_1Transaction specificOptional field submitted by merchant.
optional_2Transaction specificOptional field submitted by merchant.
optional_3Transaction specificOptional field submitted by merchant.
optional_4Transaction specificOptional field submitted by merchant.
optional_5Transaction specificOptional field submitted by merchant.
transaction_status0=Live , 100=testUsed to distinguish a test transaction where no money has been sent, from a live transaction where money has been sent.
billing_fullnameTransaction specificBilling name of customer.
billing_addressTransaction specificBilling address of customer.
billing_postcodeTransaction specificBilling postcode of customer.
delivery_fullnameTransaction specificCustomer Delivery name.
delivery_addressTransaction specificCustomer Delivery address.
delivery_postcodeTransaction specificCustomer delivery postcode.
customer_phone_numberTransaction specificCustomer phone number.
consumer_messageTransaction specificCustomer message entered on payment page.
ip_addressTransaction specificIP address of customer.
ip_countryTransaction specificCountry IP address based in.
card_countryTransaction specificCountry debit / credit card issued.
card_address_checkNot Checked, Failed, Not Available, Passed Address verification result.NotChecked = AVS Check Bypassed, Failed = Address not match, Passed = Address match, Not Available = AVS not available for card.
card_postcode_checkNot Checked, Failed, Not Available, Passed Address verification result.NotChecked = AVS Check Bypassed, Failed = postcode not match, Passed = postcode match, Not Available = AVS not available for card.
card_security_codeNot Checked, Failed, Not Available, Passed CVV2 result.NotChecked = AVS Check Bypassed, Failed = CVV2 not match, Passed = CVV2 match, Not Available = CVV2 check unavailable for card.
3d_secure_validation_checkFully Authenticated, Authentication Attempted, No Authentication Attempted3D Secure result. Fully Authenticated = 3DS Full Pass , Authentication Attempted = Attempted 3DS Check ,No Authentication Attempted = 3DS check bypassed.
net_amountTransaction specificAmount received into Nochex account after charges. (same as amount)
chargeTransaction specificNochex charge for transaction

These are the variables that will be processed between your server and the Nochex server. It is important that every variable is passed to the Nochex server exactly as it was received.

Example Code​

The below are examples of callback handlers. There are PHP, ASP and .NET examples.

<?php 
// Payment confirmation from http post 
ini_set("SMTP","mail.nochex.com" ); 
$header = "From: callback@nochex.com";
  
$your_email = '';  // your merchant account email address

  
function http_post($server, $port, $url, $vars) { 
    // get urlencoded vesion of $vars array 
    $urlencoded = ""; 
    foreach ($vars as $Index => $Value) // loop round variables and encode them to be used in query
    $urlencoded .= urlencode($Index ) . "=" . urlencode($Value) . "&"; 
    $urlencoded = substr($urlencoded,0,-1);   // returns portion of string, everything but last character

    $headers = "POST $url HTTP/1.0\r\n";  // headers to be sent to the server
    $headers .= "Content-Type: application/x-www-form-urlencoded\r\n";
	$headers .= "Host: secure.nochex.com\r\n";
    $headers .= "Content-Length: ". strlen($urlencoded) . "\r\n\r\n";  // length of the string
		
	$hostip = @gethostbyname("secure.nochex.com");

	echo "Nochex IP Address = " . $hostip . "<br/><br/>";
	
	echo "Headers = " . $headers . "";
	
    $fp = fsockopen($server, $port, $errno, $errstr, 20);  // returns file pointer
    if (!$fp) return "ERROR: fsockopen failed.\r\nError no: $errno - $errstr";  // if cannot open socket then display error message
	
    fputs($fp, $headers);  //writes to file pointer

    fputs($fp, $urlencoded);  
  
    $ret = ""; 
    while (!feof($fp)) $ret .= fgets($fp, 1024); // while it’s not the end of the file it will loop 
    fclose($fp);  // closes the connection
    return $ret; // array 
} 


// uncomment below to force a DECLINED response 
//$_POST['order_id'] = "1"; 

$response = http_post("ssl://secure.nochex.com", 443, "/callback/callback.aspx", $_POST); 

			if ($_POST['transaction_status'] == "100"){
			$status = " TEST";
			}else{
			$status = " LIVE";
			}


$debug = "IP -> " . $_SERVER['REMOTE_ADDR'] ."\r\n\r\nPOST DATA:\r\n"; 
foreach($_POST as $Index => $Value) 
$debug .= "$Index -> $Value\r\n"; 
$debug .= "\r\nRESPONSE:\r\n$response";

echo $debug;
  
if (!strstr($response, "AUTHORISED"))  {
	$msg = "Callback was not AUTHORISED. \r\n\r\n$debug";  


}else{

  $msg = "Callback was AUTHORISED. \r\n\r\n$debug"; 


} 
 
mail($your_email, "APC Debug", $msg, $header);  // sends an email explaining whether APC was successful or not, the subject will be “APC Debug” but you can change this to whatever you want.
?>

Testing Callback​

To test your callback code or script, we have provided a few instructions below;

Firstly, copy one of the callback listener examples from above. For example, the PHP code.

Next, paste the code into a text editor such as: Notepad or something similar;

Replace $to = ""; with your email address, e.g. $to ="myEmail@example.com";

Save all changes, and upload the page to your website, so you have the URL: https://mywebsite.com/nochexcallbackcurl.php go directly to the page and you will receive a declined response.

Next, create a Nochex html payment form, which will make a POST to your Nochex payment page including the callback_url parameter.

For Example;

<form method="POST" action="https://secure.nochex.com">
<input type="hidden" name="merchant_id" value="<yourmerchantID>"/>
<input type="hidden" name="amount" value="1.00"/>
<input type="hidden" name="test_transaction" value="100"/>
<input type="hidden" name="callback_url" value="<yourcallbackURL>"/>
<input type="submit" value="Make Payment" />
</form>

Replace the following; <yourmerchantID> to your Nochex registered email address/merchant ID, e.g. myEmail@example.com <yourcallbackURL> to the location of your Callback page on your website, e.g. mywebsite.com/nochexcallbackcurl.php

<form method="POST" action="https://secure.nochex.com">
<input type="hidden" name="merchant_id" value="myEmail@example.com"/>
<input type="hidden" name="amount" value="1.00"/>
<input type="hidden" name="test_transaction" value="100"/>
<input type="hidden" name="callback_url" value="https://mywebsite.com/nochexcallbackcurl.php"/>
<input type="submit" value="Make Payment" />
</form>

Save your payment form, and open it in a web browser then press your Make Payment button which will redirect you to your payment page and then go through the payment process till you have got to the Nochex success page. Once you have got to your Nochex success page, check your emails to make sure you have received an email for your recent transaction and a response of 'Authorised' from your callback script with subject line: 'Callback'

Debugging Callback​

If Callback doesn't work correctly there is a handy method of debugging your code. Add a mail function within your code that sends an email to you at different places within the code. Firstly have one that emails you right at the beginning of the code so you know for sure that the file is actually being called. Then have an email function sending the variables as this enables you to check at certain intervals in your code, whether or not the right information is being stored and are being sent correctly.

Below is a PHP code example implementing the mail function in two different places and as always when a declined response is received an email is sent with the debug details:

<?php
// Payment confirmation from http post

$your_email = 'you@domain.com'; // your merchant account email address
mail($your_email, "Callback", "Being called?");

function http_post($server, $port, $url, $vars) {
.
.
.
.
 }

$response = http_post("https://secure.nochex.com/callback/callback.aspx", $_POST);
// stores the response from the Nochex server
$debug = "IP -> " . $_SERVER['REMOTE_ADDR'] ."\r\n\r\nPOST DATA:\r\n";
foreach($_POST as $Index => $Value)
$debug .= "$Index -> $Value\r\n";
$debug .= "\r\nRESPONSE:\r\n$response";
mail($your_email, "Callback", $debug);

if (!strstr($response, "AUTHORISED")) { // searches response to see if AUTHORISED is present if it
isn’t a failure message is displayed
 $msg = "Callback was not AUTHORISED.\r\n\r\n$debug"; // displays debug message
}
else {
 $msg = "Callback was AUTHORISED."; // if AUTHORISED was found in the response then it was
successful
 // whatever else you want to do
}
mail($your_email, "Callback Debug", $msg); // sends an email explaining whether Callback was
successful or not, the subject will be “Callback Debug” but you can change this to whatever you
want.
?>

Callback Troubleshooting Tips​

"DECLINED" Message​

If you receive a DECLINED response:

  • Go back and carefully check your code, make sure that each variable is passed to the Nochex server without changing them at all.
  • Ensure that you are posting the information to the right URL, https://secure.nochex.com/callback/callback.aspx

No Message Received​

If your Callback listener/script doesn't send an email to you when it should:

  • Make sure you have Callback enabled on your Nochex account by contacting us.
  • Check that the Callback listener is actually being called by creating a test email script, by doing this you will receive an email and able to conclude that it is a problem with your Callback listener code.
  • Check your code carefully to ensure the right email address is being used.
  • Check that your firewall settings aren't blocking the HTTP POST messages from Nochex, if you are unsure contact your website developer or hosting company to check this.
  • Take another look at this guide and the examples within it to help, and expand on the examples as they are all fully working examples.