iBasic Integration Guide

Overview

This guide deals with the integration of the Pay Offline payment system into a merchant site using the iBasic integration method. To be able to generate the PayOffline barcode invoice for a customer order, certain parameters need to be sent to the PayOffline transaction server. This document will specify the mandatory and optional parameters as well as how to send the parameters to the PayOffline transaction server.

PayOffline can make use of callbacks to inform merchants of an orders payment status, the Callback Guide discusses all the different types of callbacks sent by PayOffline.

It is possible, if required, to sign all data sent to the PayOffline server, this gaurantees that the information sent to us by the merchant is the data that we process. The Security Guide discusses the data signing technique in more detail.

A Typical iBasic order flow overview

Communicating with PayOffline using Form Post

The iBasic method of integration uses HTML forms to "Post" the order details to PayOffline over an SSL connection. The PayOffline SSL certificate will encrypt all communication between the merchant server and PayOffline transaction server.

A HTML Form is posted from the merchant server to the secure PayOffline transaction server. The form should contain all the mandatory parameters and any optional parameters. As a result of the FORM being posted to PayOffline, the customer is redirected to the PayOffline server.
After visting a PayOffline confirmation page an order invoice page hosted on the PayOffline server is displayed to the customer.
Once the customer has settled thier invoice at a pazone outlet, we recieve notifcation of payment 24 hours after payment is made, an email is then sent to the merchants email address informing them of payment. Optionally, a callback can be sent to a server side script.

Posting order details to PayOffline

A typical transaction starts with an HTML form on the merchant server POSTing a request to the PayOffline transaction server. The action property of the form should be:

https://secure.payoffline.com/process/invoice.aspx

eg.

<form name="YourFormName" action="https://secure.payoffline.com/process/invoice.aspx" method="POST">
...
</form>

The following form action should be used for iBasic integration testing:

http://test.payoffline.com/testtrans/ibasic.aspx

eg.

<form name="YourFormName" action="http://test.payoffline.com/testtrans/ibasic.aspx" method="POST">
...
</form>

Merchants and developers must ensure that adequate testing has been completed before processing live transactions.

Form Parameters

The table below specfies all mandatory and optional parameters that can be posted to the Payoffline transaction server in order for an invoice to be generated:

Form Parameters
Name	Form Field Name	Type	Mandatory/ Optional	Description
Merchant Key	mid	alpha numeric (255)	Mandatory	This is your PayOffline merchant ID, you will be assigned a merchant id after we have approved your application. Example: 653ADC55E
Order ID	oid	alpha numeric (255)	Mandatory	A unique order ID created by yourself. This can be used to refer to a transaction at a later date. Example: ABC12345
Amount	amt	decimal	Mandatory	This is the total amount of the customer order. If you want to sell multiple items, you must calculate the total amount on your own site, this should also include any applicable shipping charges or taxes. The amount should contain no currency symbols or formatting. A decimal point must be used. Example: £1,999.99 = 1999.99
Expiry Days	expdays	numeric	Optional	This is the number of days in which the invoice will expire. If payment is not received before the expiry date you will be sent an email to inform you that payment was not received. If a Callback URL is provided then a payment expiry message is also sent to the Callback URL (see below). Example: 30 days = 30
Callback URL	callbackurl	alpha numeric (255)	Optional	This is the url of a server side script on your server that will process callback messages from PayOffline. Example: http://www.yoursite.com/proc.php
Return URL	returl	alpha numeric (255)	Optional	This is the url customers are sent to if they click the "return to merchant site" link on the invoice page. Example: http://www.yoursite.com/thanks.php
Cancel URL	cancelurl	alpha numeric (255)	Optional	This is the url customers are sent to if they cancel at the confirmation page. The confirmation page is displayed before the order invoice page. Example: http://www.yoursite.com/cancelled.php
Callback Variables	callbackvars	alpha numeric (4096)	Optional	This field is returned when callbacks are sent to your server. You can use this field to pass any information relavent to the order. Example: itm1=DVD&amt1=19.99&qty1=1
MD5 Signature	sign	alpha numeric (32)	Optional *	This is the MD5 signature of the form data. The MD5 signature is used to ensure the validatity of the data recieved by PayOffline, The MD5 signature is generated by concatenating all the form parameter values with a secret key known only to you and PayOffline. Please see the security guide for more information on MD5 signatures. Example: 3be9fd25c0cedabce8012a67bd6bd865

* MD5 Signature field can be made mandatory, please see the security guide for more details

Example Forms

For the following order details to be sent to the PayOffline transaction server...

Order ID: ABC12345
Merchant ID: PO123
Order Amount: £19.99
Invoice Expiry: 30 days
Callback URL: http://www.yourserver.com/proc.php
Return URL: http://www.yourserver.com/thanks.php
Cancel URL: http://www.yourserver.com/cancelled.php
Callback Variables: itm1=DVD&amt1=19.99&qty1=1

a typical test form will look like the following:

<form name="frmPayOffline" action="http://test.payoffline.com/testtrans/ibasic.aspx" method="POST">
    <input type="hidden" name="mid" value="AB123">
    <input type="hidden" name="oid" value="ABC12345">
    <input type="hidden" name="amt" value="19.99">
    <input type="hidden" name="expdays" value="30">
    <input type="hidden" name="callbackurl" value="http://www.yourserver.com/proc.php">
    <input type="hidden" name="returl" value="http://www.yourserver.com/thanks.php">
    <input type="hidden" name="cancelurl" value="http://www.yourserver.com/cancelled.php">
    <input type="hidden" name="callbackvars" value="itm1=DVD&amt1=19.99&qty1=1">
    <input type="submit" name="btnPayOffline" value="Test PayOffline">
</form>

A typical live form will look like the following:

<form name="frmPayOffline" action="https://secure.payoffline.com/process/invoice.aspx" method="POST">
    <input type="hidden" name="mid" value="PO123">
    <input type="hidden" name="oid" value="ABC12345">
    <input type="hidden" name="amt" value="19.99">
    <input type="hidden" name="expdays" value="30">
    <input type="hidden" name="callbackurl" value="http://www.yourserver.com/proc.php">
    <input type="hidden" name="returl" value="http://www.yourserver.com/thanks.php">
    <input type="hidden" name="cancelurl" value="http://www.yourserver.com/cancelled.php">
    <input type="hidden" name="callbackvars" value="itm1=DVD&amt1=19.99&qty1=1">
    <input type="hidden" name="sign" value="62e9c06822a8ce141536621c846b49ae">
    <input type="submit" name="btnPayOffline" value="PayOffline">
</form>

In the examples above hidden form fields are used to hide the parameter values from the Customer.

Security

In order for you to ensure that PayOffline only processes valid order details you will need to provide the MD5 signature field. Please visit the Security Guide for more details.

PayOffline suggest that, whenever possible, an MD5 signature field should always be included in the form sent to PayOffline.

Callbacks

Callbacks are used to inform you of the payment status for a particular order that your website or shopping cart has sent to PayOffline.

You will receive callbacks for the following actions:

Full Payment Recieved
Partial Payment Recieved
Excess Payment Recieved
Payment Expiry

For more information about what is sent in the Callback to your server, please visit our Callback Guide.