Skip to main content

APC

Introduction to APC​

Automatic Payment Confirmation (APC) allows you to integrate your Nochex payments with your back-end operations to get immediate onfirmation and authentication of the Nochex payments you receive.

Using APC 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

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

What is APC?​

APC authenticates a payment that is made into your Nochex account by communicating with your server. To start using APC you are required to create a listener, the following information explains what a listener exactly is and how to implement one.

APC listener​

To process APC responses you will need a listener page, this is script or code that will wait for an APC response from Nochex.

After your listener has received a response it is required to send the same information back to the Nochex server to confirm the details re 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 (For example: Processing to Paid).
  • Update list of customer details
  • Enable customers to download media e.g. purchasing an eBook

Your APC listener can be written in any scripting language or programming language you choose, example code that could be used is included in this document or found here, and hosted on your web server.

Once you have uploaded the listener page to your web server, enter the URL to your APC listener into the Callback URL field within the Payment Page Setup in your Nochex account.

Creating a listener​

Below is the functionality that must be included when creating your APC 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/apc/apc.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​

  1. Login to your Nochex account

  2. Click Payment Page Setup

  3. Specify the URL for your APC listener in the Call back URL field.

You can also set up the call back URL within the HTML form POST to Nochex using the below parameter.

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://myWebsite.com/apchandler.php">
<input type="submit" value="Pay on Credit or Debit Card with Nochex" />
</form>

APC Step-by-Step​

How APC works​

  1. A customer visits your website and decides to use the Nochex payment option.

  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 directed to the Nochex confirmation page:

payment page confirmation

  1. Once the payment has been made, in the background the Nochex server will post a confirmation to your APC listener. The confirmation includes the information about the transaction, such as; the amount paid as well as a security key unique to that transaction.

  2. Once your server receives the confirmation, the APC listener should return all of the information posted to you to the Nochex APC 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.

APC Diagram​

APC diagram

Legend:
red arrowThe red arrows show the customer's experience, they just see the immediate effects. They will see the updated webpage after APC has been successful.
blue arrowThe blue arrow shows the APC 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 APC listener.

  5. The Nochex server will then send an APC response to your APC listener 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 APC listener, some of which include; sending an email with the APC 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.

APC Variables​

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.

VariablesValueDescriptionExample
to_emailTransaction specificEmail address of the payment recipient.merchant@nochex.com
from_emailTransaction specificEmail address of the payment sender.customer@nochex.com
transaction_idTransaction specificUnique code generated to distinguish transactions.1793359
transaction_dateTransaction specificDate/time stamp of transaction.15/02/2010 17:20:46
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 transaction999999
amountTransaction specificFull amount of the customer's payment.5.99
security_keyTransaction specificSystem generated key (for Nochex use)16736
statusLive or TestUsed to distinguish a test transaction where no money has been sent, from a live transaction where money has been sent.test

Example Code​

The below are code sample of APC listeners:

<?php 
// Payment confirmation from http post 
  
$your_email = 'your_email@example.com';  // 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: www.nochex.com\r\n";
    $headers .= "Content-Length: ". strlen($urlencoded) . "\r\n\r\n";  // length of the string
		
	//$hostip = @gethostbyname("www.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"; 

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

// HTTP  
//$response = http_post("secure.nochex.com", 80, "/apc/apc.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"; 

echo $debug;
  
if (!strstr($response, "AUTHORISED")) {  // searches response to see if AUTHORISED is present if it isn’t a failure message is displayed
    $msg = "APC was not AUTHORISED.\r\n\r\n$debug";  // displays debug message
} 
else { 
    $msg = "APC was AUTHORISED."; // if AUTHORISED was found in the response then it was successful
    // whatever else you want to do 
} 
 
mail($your_email, "APC Debug", $msg);  // 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 APC​

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

Firstly, copy one of our APC listener examples from before, 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/yourAPCfile.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/yourAPCfile.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/yourAPCfile.php"/>
<input type="submit" value="Make Payment" />
</form>

Save your payment form, and open it in a web browser

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'

You can also complete a test transaction from your Nochex control panel. Just follow these steps:

  1. Login to your Nochex account

  2. At the control panel select "Payments Page Setup" (only available if you have a merchant account)

  3. Enter your APC handler URL in the "Call back URL" field and click "Save Changes"

  4. Click the "Test Transaction" button at the bottom of the page and complete a test transaction

  5. Your APC handler code should contain a mail/debug function so after an APC response is obtained you know the result

Debugging APC​

If APC 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, "APC", "Being called?");

function http_post($server, $port, $url, $vars) {
.
.
.
.
 }
$response = http_post("ssl://secure.nochex.com", 443, "/apc/apc.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, "APC", $debug);

if (!strstr($response, "AUTHORISED")) { // searches response to see if AUTHORISED is present if it isn't a failure message is displayed
 $msg = "APC was not AUTHORISED.\r\n\r\n$debug"; // displays debug message
}
else {
 $msg = "APC was AUTHORISED."; // if AUTHORISED was found in the response then it was
successful
 // whatever else you want to do
}
mail($your_email, "APC Debug", $msg); // 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.
?>

APC 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/apc/apc.aspx

No Message Received​

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

  • Check that the APC listener is actually being called by creating a test email script, if by doing this you receive an email you can conclude that there is a problem with your APC 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 of this contact your hosting company.

  • Look back at this guide and use the working examples and expand on them.