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 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
Content-Type: application/json
  "cart_items": [
    "description": "Man sized tissues",
    "quantity": 1,
    "cost": 1000,
    "image": ""

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:



your Cloud Payments username


The invoice number or transaction reference


The currency for the transaction


The transaction total


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'


On the end of the URL


Your website's base URL e.g.


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

The resulting request URL would be:

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:




The line-item description



The number of items in the cart for this line item



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


String (URL)

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

A successful response will look like:

Content-Type: application/json

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

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

Content-Type: application/json

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



Indicates if the token request was successful



The Masterpass request token



The Masterpass checkout ID


Array (String)

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


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.