Cloud Payments Documentation

Welcome to the Cloud Payments developer hub. You'll find comprehensive guides and documentation to help you start working with Cloud Payments as quickly as possible.

Get Started    API Reference

Masterpass

Masterpass gives your customers a faster, easier way to checkout online and gives you a way to increase sales without significantly changing the way you process payments now.

Masterpass Customer Checkout Workflow

  • A customer creates their account once, or a wallet is made available through the customer's bank.
  • The customer chooses to Buy with Masterpass on the merchants website and only needs to login and then select their card and shipping address.
  • The customers credit card details are retrieved securely by Cloud Payments and your systems are not exposed to the PCI Scope for this data.
  • The new Masterpass lightbox allows the customer to stay on your website and offers a streamlined checkout process.

Using Masterpass on your Website

Cloud Payments has pre-built support for Masterpass in WooCommerce with version 1.5.1 of our plugin. We are also building plugins and extensions for other supported carts, however we do not yet have an expected release date for these other carts.

In order to add Masterpass to your ecommerce website or application:

  1. Review the Masterpass agreement - upon acceptance Cloud Payments will provision your Masterpass Merchant account.
  2. Cloud Payments will notify you once your account is provisioned.
  3. Fetch a request token from Cloud Payments' PayNow service - in this step you may also optionally include shopping cart details to be displayed within the Masterpass light box.
  4. Handle the callback from the light box and submit the details (checkout resource URL, OAuth token and OAuth verifier) to Cloud Payments along with your Tokenization or Purchase request.

Setting up your Masterpass Merchant Account

In order to setup the Masterpass Merchant Account you must first review and accept the Masterpass Terms of Use. To do this:

  1. Log into the Merchant Dashboard.
  2. Click on the My Account link on the left hand side and then click the Masterpass link.
  3. Review and accept the Masterpass Terms of Use.
  4. Once the Terms of Use has been accepted your account will be provisioned. You will receive an email notification once this is done.

Fetch the Request Token

In order to run the Masterpass lightbox, a request token is used along with the Checkout ID. As part of this request, Cloud Payments will setup the shopping cart details for the consumer. Merchants are advised to provide shopping cart items if available, however this is optional.
To fetch a request token a POST request needs to be sent to the Cloud Payments PayNow service:

POST /v2/YOUR_USERNAME/INVOICE-123/AUD/10.00/abcd1234/masterpass_token?origin_url=http://your_website_base_url&callback_path=/your_cart_page HTTP/1.1
Server: paynow.sandbox.fatzebra.com.au
Content-Type: application/json
 
{
  "cart_items": [
    "description": "Man sized tissues",
    "quantity": 1,
    "cost": 1000,
    "image": "https://www.mansizedtissues.com/images/tissue-box.png"
  ]
}

The URL for the Masterpass token request contains a few items relative to the transaction, followed by a hash used to verify the data. The URL parameters are:

Parameter
Description

username

your Cloud Payments username

invoice_number

The invoice number or transaction reference

currency

The currency for the transaction

amount

The transaction total

hash

A hash of the invoice details to ensure no parameter tampering, generated like so:

params_string = [username, invoice_number, currency, amount].join(':')
`HMAC::MD5(shared_secret, params_string)`

For example, with the username 'mantissues', invoice number ABC123, currency of AUD and amount of 10.00 the params_string would be: 'mantissues:ABC123:AUD:10.00'

masterpass_token

On the end of the URL

origin_url

Your website's base URL e.g. https://www.mansizedtissues.com

callback_path

The path to the page where the Masterpass button is displayed (e.g. /cart for the cart page)

The resulting request URL would be:
https://paynow.pmnts-sandbox.io/v2/mantissues/ABC123/AUD/10.00/abcdef1234567890/masterpass_token?origin_url=http://www.mantissues.com.au&callback_path=/cart

For more details on calculating this value please see the Hosted Payment Pages documentation.

The cart items request data should include an array of objects with the following fields:

Parameter
Type
Description

description

String

The line-item description

quantity

Integer

The number of items in the cart for this line item

cost

Integer

The value of the minimum quantity of the items in the lowest denomination (e.g. cents)

image

String (URL)

The URL of the item image. This URL should be a secure (HTTPS) URL.

A successful response will look like:

HTTP 200 OK
Content-Type: application/json

{
  "successful": true,
  "token": "abc123",
  "checkout_id": "abc123"
}

Or, if there was an error requesting the Masterpass token:

HTTP 200 OK
Content-Type: application/json

{
  "successful": false,
  "errors": ["An error occurred. Please contact support."]
}
Response field
Type
Description

successful

Boolean

Indicates if the token request was successful

token

String

The Masterpass request token

checkout_id

String

The Masterpass checkout ID

errors

Array (String)

Any error messages associated with the request. This will only be present if successful is false.

Masterpass


Masterpass gives your customers a faster, easier way to checkout online and gives you a way to increase sales without significantly changing the way you process payments now.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.