Callback Guide

What is a Callback?

A Callback is the mechanism used by PayOffline to notify merchants of an orders payment status. Essentially a callback entails PayOffline using a http form POST to the merchant callback URL. The form contains parameters that can be used to determine the reason the callback is being sent and the details of the order that the callback relates to.

Your server side script should be able to process the messages sent by PayOffline without generating an error. To ensure your callback handling is working as you intend, we suggest you do adequate testing using our test server before going live.

Callback Overview

Specifying the Callback Page using iBasic

You can specify the location of your callback script when you make the initial POST request to our servers.

For example:

<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.yoursite.com/proc.php">
    <input type="hidden" name="returl" value="http://www.yoursite.com/thanks.php">
    <input type="hidden" name="cancelurl" value="http://www.yoursite.com/cancelled.php">
    <input type="hidden" name="callbackvars" value="itm1=DVD&amt1=19.99&qty1=1">
</form>

Specifying the Callback Page using iPro

You can specify the location of your callback script when you make the remote procedure call to the InsertTransaction operation.

For example:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <InsertTransaction xmlns="http://tempuri.org/">
      <mid>PO123</mid>
      <oid>ABC12345</oid>
      <amt>19.99</amt>
      <expdays>30</expdays>
      <callbackurl>http://www.yoursite.com/proc.php</callbackurl>
      <sign>a20bf0fe8e530adf9c5e3b9f35c32ce2</sign>
    </InsertTransaction>
  </soap:Body>
</soap:Envelope>

Callback Notfications

The table belows specifies the different types of notifications that PayOffline sends via callbacks.

Notification Types
Notification Message	Message Code	Description
Full Payment Received	0	Full payment was made by the customer at the payment outlet
Partial Payment Received	1	Only partial payment was made by the customer at the payment outlet, you should not despatch goods until you receive a "Full Payment Received" message. PayOffline invoices clearly state that payment must be made in full at the payment outlet so this situation should not occur however, it is theoretically possible for only partial payment to be accepted.
Excess Payment Received	2	Payment was made by the customer at the payment outlet but for more than the actual order value. As with partial payment, this situation should not occur however, it is possible.
Payment Not Received	3	Payment has still not been received for a particular order. You can use this message to send out an automated email to the customer reminding them to make payment.
Order Expired	4	This message is sent once the invoice has expired. You can use this message to send out an automated email to the customer informing them that the order has been cancelled. You can also use this message to restock the products associated with the order.
Payment Pending	5	This message is sent when the customer proceeds to the invoice page from the PayOffline confirmation page. You can use this message to set the status of the order to pending.

Callback Parameters

The table below specifies the parameters that are returned with all callbacks from PayOffline.

Callback Parameters

Name

Form Field Name

Type

Description

Merchant ID

mid

alpha numeric (255)

This is your PayOffline Merchant ID.

Transaction ID

transid

alpha numeric (255)

This is a unique PayOffline transaction ID.

Order ID

oid

alpha numeric (255)

We send you back the same ID that you sent us with your mandatory parameters in your original POST to our transaction server. You can determine which of your orders the notification relates to by using the Order ID value.

Amount

amt

decimal

This is the amount paid at the payment outlet by your customer.

In the case of a "Full Payment Recieved" notifications the amount value should the same as the order total.

For "Partial Payment Received" notifications the amount value will be less that the order total.

For "Excess Payment Received" notifications the amount value will be more than the order total.

For "Order Expired" notifications the amount value will be 0.

Message Code

code

numeric

Notification Message	Message Code Value
Full Payment Received	0
Partial Payment Received	1
Excess Payment Received	2
Payment Not Received	3
Order Expired	4
Payment Pending	5

Callback Variables

callbackvars

alphanumeric

If the Callback Variables field is sent in the request to the PayOffline transaction server then it is returned with any callbacks from the PayOffline server to the merchant server. This field is not supported by iPro and so is not returned in the callback when using iPro integration.

Signature

sign

alphanumeric (32)

This is the callback message signature, it is only returned if the "always use MD5 signatures" option is checked in the merchant admin centre. Please see the security guide for more information on MD5 signatures.

Callback Example

using the form below as an example POST from a merchant server

<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.yoursite.com/proc.php">
    <input type="hidden" name="returl" value="http://www.yoursite.com/thanks.php">
    <input type="hidden" name="cancelurl" value="http://www.yoursite.com/cancelled.php">
    <input type="hidden" name="callbackvars" value="itm1=DVD&amt1=19.99&qty1=1">
</form>

The following messages could be returned to the callback URL, http://www.yoursite.com/proc.php

Full Payment Received:

mid=PO123&transid=1123&oid=ABC12345&amount=19.99&code=0&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1

Partial Payment Received:

mid=PO123&transid=1123&oid=ABC12345&amount=15.00&code=1&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1

Excess Payment Received:

mid=PO123&transid=1123&oid=ABC12345&amount=21.99&code=2&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1

Payment Not Received:

mid=PO123&transid=1123&oid=ABC12345&amount=19.99&code=3&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1

Order Expired:

mid=PO123&transid=1123&oid=ABC12345&amount=0&code=4&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1

Payment Pending:

mid=PO123&transid=1123&oid=ABC12345&amount=19.99&code=5&callbackvars=itm1%3DDVD%26amt1%3D19.99%26qty1%3D1