Security

PayOffline can process MD5 signatures sent to the PayOffline transaction server. The signature can be used to verify that the the data that we receive has not been tampered with.

This encrypted signature can also be included in callbacks sent by PayOffline. You must enable the "Always use MD5 signatures" option in the merchant administration centre to enable callback signatures (see Figure 1).

Figure 1. MD5 Settings

What is MD5 ?

MD5 is an cryptographic hash function that is commonly used to verify the integrity of data. The 128-bit (16-byte) MD5 hashes, also termed as fingerprints or message digests, are typically represented as a sequence of 32 hexadecimal digits.

How to Enable MD5

To use MD5 signatures, you must specify a secret key, this key is used during the data signing process. This key is known to only you and PayOffline, you should not tell any one your secret key. If you believe that your key has been compromised you should change it immediately.

You can set your secret key in your merchant administration centre in the "Transaction Setting" page (see Figure 1).

Using MD5 Signature with iBasic

When using iBasic to integrate with PayOffline, the MD5 Signature value is created by concatenating the...

merchant ID
order ID
amount
expiry days
callback url
return url
cancel url
callback variables
secret key

Generating the signature for iBasic...

The resultant MD5 signature should be added to a field named "sign", eg.

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

As you can see from the form above, the secret key is not included in the form.

Using MD5 signature with iPro

When using iPro to integrate with PayOffline, the MD5 Signature value is created by concatenating the...

merchant ID
order ID
amount
expiry days
callback url
secret key

Generating the signature for iPro...

The resultant MD5 signature should be provided in the "sign" parameter, eg.

<?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>

If you have specified a secret key and checked the ""Always use MD5 Signatures" in the Administration Centre, PayOffline will use your key to sign the XML data returned.

The Barcode details signature is created by concatenating the...

BarcodeNumber
BarcodeImage
BarcodeURL
BarcodeExpiry

The Order details signature, which should match the signature you generated, is created by concatenating the...

merchant ID
order ID
amount
expiry days
callback url
secret key

A typical XML response would look like...

<?xml version="1.0" encoding="utf-8" ?> 
<dsBarcode xmlns="http://tempuri.org/">
    <xs:schema id="dsBarcode" targetNamespace="http://tempuri.org/dsBarcode.xsd" xmlns:mstns="http://tempuri.org/dsBarcode.xsd" xmlns="http://tempuri.org/dsBarcode.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" attributeFormDefault="qualified" elementFormDefault="qualified">
        <!--schema definition removed-->
    </xs:schema>
    <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
        <dsBarcode xmlns="http://tempuri.org/dsBarcode.xsd">
            <Results diffgr:id="Results1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
                <Result>1</Result> 
                <Description>Transaction successful</Description> 
            </Results>
            <Barcode diffgr:id="Barcode1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
                <BarcodeNumber>6335554007001000602</BarcodeNumber> 
                <BarcodeImage>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AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==</BarcodeImage> 
                <BarcodeURL>http://secure.payoffline.com/Common/BarCodeDisplay.aspx?skey=FSi/Dn58Lic=</BarcodeURL> 
                <BarcodeExpiry>2007-08-04T00:00:00+01:00</BarcodeExpiry> 
                <sign>ec02a3ccb0458a286acfb27d174e6d4</sign> 
            </Barcode>
            <Order diffgr:id="Order1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
                <mid>PO123</mid>
                <oid>ABC12345</oid>
                <amt>19.99</amt>
                <expdays>30</expdays>
                <callbackurl>http://www.yoursite.com/proc.php</callbackurl>
                <sign>a20bf0fe8e530adf9c5e3b9f35c32ce2</sign>
            </Order>
        </dsBarcode>
    </diffgr:diffgram>
</dsBarcode>

Callback MD5 Signatures

All callbacks sent by PayOffline can be signed with an MD5 Signature using your secret key. To enable callback signatures you need to check the "Always check for MD5 signatures" option in the Merchant Administration Centre (see Figure 1). Because callbacks can be used with both iBasic and iPro, the parameters that are signed are different for the two different integration options.

The MD5 callback signature value is created by concatenating the merchant ID, transaction ID, order ID, amount, message code and callback variables along with your secret key.

Callback signature...

mid=PO123&transid=TR12345&oid=ABC12345&amt=19.99&code=0&callbackvars=callbackvars&sign=ba95333a0136dc0094ac62e7f11309c0

Please Note: In the case of iPro, the callback variables fields is not included in the list of fields that are signed, this is becasue iPro does not support the callback variables field and it is not returned in the callback message.

Validating MD5 Signatures

When PayOffline receives the request from your server, the same process takes place to build the MD5 signature.

If the string created by PayOffline matches the string sent by you in the value of the sign paramter, then we know that the request came from you and that none of the data used to create the signature was altered in transit, in this situation the data is then processed.

If the signatures do not match then, for iBasic a message is displayed to the customer informing them that there was a problem authenticating and in the case of iPro, an error message is returned in the results node of the XML response.

Please note that the encryption process cannot be implemented client side, for example using Javascript, this operation must happen server side.

Making MD5 Signature Mandatory

If you have provided a secret key in the Administration Centre, PayOffline will check for the signature, if it finds the signature it will validate it, if it does not find the sign parameter it will still process the form data. To make the sign parameter a mandatory field you should check the "Always check for MD5 signature" in the merchant admin centre, this also enables callback signatures.

Troubleshooting

If you experience problems with MD5 signatures, please check the following...

Ensure you are using the correct Secret Key, the secret key is case sensitive so "SecretKey" would produce a different signature to "secretkey".
The order in which the variables are concatenated is important, if you do not build the string in the correct order PayOffline will return an error message.
The case of the data that you are signing is important. Signing "thebrowndog" will produce a different signature to "TheBrownDog". Do not change the case of the data before signing it.
When generating the signature make sure that you use UTF-8 encoding and not Unicode

If you continue to experience problems with MD5 signatures, please contact us for assistance.

MD5 Resources

.NET
For a Visual Basic and C# MD5 Hash class compatible with all versions of the .NET framework. please visit http://msdn2.microsoft.com/en-us/library/system.security.cryptography.md5.aspx.

ASP
There is an ASP MD5 Hash function available for download at http://rossm.net/Electronics/Computers/Software/ASP/#MD5.

PHP
the MD5 Hash function for PHP is inbuilt so there is no need to install additional components, please visit http://uk.php.net/md5 for more information

Perl
For a Perl interface to the MD5 Algorithm, please visit http://perldoc.perl.org/Digest/MD5.html.