V2 - Overview

Currently the hosted payment page supports three methods of implementation:

• Standard Hosted Page (i.e. redirection from the merchants website to the payment page)
• iframe embedded page
• Accounting platform payment page (for example Xero or Saasu)

The V2 UI looks like this, but can be restyled by using the css parameter documented below:

Usage

The data sent between the merchant and Fat Zebra, and from Fat Zebra to the merchant is sent in the request URL - to ensure that this has not been tampered with the payload includes a verification value, which is a signed-hash based on the payload values, using a shared secret between the merchant and Fat Zebra. This process has been closely modeled on the Fat Zebra Direct Post method - it is recommend you review this documentation for further details which may not be covered here.

URLs

There are two different URLs for the PayNow service - one for the Live environment and one for the Sandbox environment:

Request

In order to direct the customer to the hosted payment page the merchants website should prepare the following URL and either use this as the redirect destination, or as the IFRAME source:

https://paynow.pmnts.io/v2/[username]/[reference]/[currency]/[amount]/[hash]

URL Parameters

The following parameters are required and are used to build the URL which the user should be redirected to (or as the source for the IFRAME):

Options

Provide any of the following as query parameters to specify display options - these are optional parameters:

Note on external CSS: When external CSS specified in the options the hosted payment page a number of verification and sanitisation steps are taken before rendering the CSS in the page, including:

• Verifying the URL specified is served over HTTPS and is in-fact a CSS file
• Verifying that the css_signature matches the URL
• Scrubbing any potentially dangerous CSS statements from the file

After successful verification and sanitising , the filtered CSS is cached by the Hosted Payment Page for 5 minutes. If the cache needs to be updated, the following options are available:

• Change the URL and update the signature to reflect - the CSS cache uses the filename and merchant ID as the cache key, so changing this will force the cache to be updated

Verification Value Calculation

There are two points of verification for requests - once when the request is received by Fat Zebra (when the hosted page is rendered to the user), and once when the response is returned to the merchant - it is important that the response is verified by the merchant to ensure that the response has not been tampered with by malicious users.

Request Verification (Redirect to Fat Zebra)

The request received by Fat Zebra will be verified with the following steps:

1. The reference, currency, amount, and if present, hide_card_holder and return_path will be concatenated into a string, joined by colons:

https://paynow.pmnts.io/v2/samsbooks/INV1121/AUD/100.25/xxxxxxxxxxx&hide_card_holder=true -> "INV1121:100.25:AUD:true"

If hide_card_holderand/or return_path is not included, they will be omitted:

https://paynow.pmnts.io/v2/samsbooks/INV1121/AUD/100.25/xxxxxxxxxxx&hide_card_holder=true -> "INV1121:100.25:AUD"

2. The value of this string will then be hashed with a HMAC-MD5, using the shared-secret known by Fat Zebra and the merchant (please contact Fat Zebra Support if you are unsure of where to find this shared secret).

shared_secret = "<<sharedSecret>>"
verification = hmac_md5(shared_secret, "INV1121:100.25:AUD:true")

Response Verification (Purchases)

For purchases the response verification will consist of the response code, success indicator, amount, currency, transaction ID and the card token:

https://www.samsbooks.com/payment/callback?r=1&successful=true&amount=10025&currency=AUD&id=001-P-ABCDG1124&token=abcd1234&v=xxxxx....... -> "1:true:10025:AUD:001-P-ABCDG1123:abcd1234"
shared_secret = "<<sharedSecret>>"
verification = hmac_md5(shared_secret, "1:true:10025:AUD:001-P-ABCDG1123:abcd1234")
 
# v == verification should be true

The response for purchases will also include the following:

Response Verification (Tokenization)

For tokenization the response verification will consist of the response code, and the card token:

https://www.samsbooks.com/payment/callback?r=1&token=abcd1234&v=xxxxxxxxx........ -> "1:abcd1234"
shared_secret = "<<sharedSecret>>"
verification = hmac_md5(shared_secret, "1:abcd1234")
# v == verification should be true

The response for tokenization will also include the following:

Response Codes

The following response codes are used when a redirect URL is provided:

IFRAME and postMessage Support

The Hosted Payment Page supports being embedded in an IFRAME and communicating back to the parent window via the postMessage function. In order to support this the following needs to be done:

1. The postmessage=true parameter needs to be added to the URL
2. The following code should be added to handle the messages from the IFRAME:

window.paymentHost = "https://paynow.pmnts-sandbox.io";
 
var messageListener = function(event) {
  if (event.origin !== window.paymentHost) {
    return;
  }
 
  // Older browsers will have a query-string style data payload
  // Whereas newer browsers will have an object
  var payload = event.data;
  if (typeof event.data == 'string') {
    if (/\[object/i.test(event.data)) {
        alert("Sorry, it looks like there has been a problem communicating with your browser..."); // Raised if the serialization failed
    }
    // Deserialize into an object
    var pairs = payload.split("&");
    payload = {};
    for (var i = 0; i < pairs.length; i++) {
        var element = pairs[i];
        var kv = element.split("=");
        payload[kv[0]] = kv[1];
    }
  }
  if ('data' in payload) {
    var payload = payload.data;
  }
  switch (payload.message) {
    case "transaction.complete":
      // Handle the transaction complete message.
      // Payload will be in e.data.data (eg. payload.data.r == 1)
      return true;
    case "transaction.processing":
      // Handle the processing of the transaction - implementation optional.
      return true;
    case "transaction.cancelled":
      // Handle the transaction being cancelled (i.e. show message, re-display the window etc).
      return true;
  }
};
 
if (window.addEventListener) { window.addEventListener("message", messageListener); }
else { window.attachEvent("onmessage", messageListener); }

Testing

Standard Fat Zebra test procedures apply for the Hosted Payment Page.

For a successful transaction you should choose the MasterCard ending in 0014. If this card is not present (as this is a shared account) it can be re-added with the following details: