Click to Pay - Hosted Payment Page

Mastercard Click to Pay securely stores users credit cards so that they can retrieve them during a checkout process. You can direct this integration to retrieve a particular user's cards by providing the email or mobile query parameters in the request.

Mastercard Click to Pay will also remember users across different checkout sessions, even across different merchants. If the user is known via this route, they will be taken straight to their list of cards within the "User Flow" section shown below.

User Flow

When these parameters are passed, this integration will automatically perform a Click to Pay user lookup. If the user is found, then the user will be prompted to enter an OTP code to verify themselves with the Click to Pay system:

If the OTP code is correct, then the user will be shown a list of their cards:

When the card is selected, the confirmation screen appears:

Clicking "Confirm payment" will show the Mastercard Click to Pay confirmation loading screen while the payment is being processed:

Once the payment has been processed, you will see a receipt screen:

Alternatively, if you have provided a return_path parameter during the initial checkout flow, the user will be redirected to that path instead.


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

EnvironmentBASE URL


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:[username]/[reference]/[currency]/[amount]/[hash]

User identification URL Parameters

The Click to Pay integration also allows you to pass in two parameters to identify your users.

emailstringThe email address for your user
mobilestringThe mobile number for your user. Can either be in a format of 0491 570 006 or can include a country code: +61 491 570 006

If you pass both, a lookup will be attempted first for email, and then mobile.

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):

usernamestringThe merchants Fat Zebra username
referencestringThe invoice number or order reference
currencystring (3 characters)The ISO-4217 3-letter currency code for the transaction
amountnumberThe amount of the transaction, as a decimal value.

For currencies which do not make use of the decimal/cent value this should be omitted as 00 (e.g. 300.00 for ¥300)
hashstringThe hash is a MD5 hexdigest of a string compiled from the request parameters.
See below (Verification Value Calculation) for more details.


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

authbooleanIf this is set the card being tokenized or the transaction processed will have an auth for the amount specified in the request performed. This can be used to verify the card
details are valid before storing.
hide_confirm_buttonbooleanHides the "Confirm Payment" button on the final "Confirmation" step of the Click to Pay checkout form for when the checkout should be triggered by the parent frame (via a postmessage)false
return_pathstringThe return URL for the transaction success - if this is omitted the result will be displayed on screen to the customer
Note: if the a URL is specified it must be included in the verification hash. This may be a non-resolving URL for callback handling in mobile
applications if required (e.g. paymentcallback://....)
return_targetstringThe target for the form post (e.g. post back to _parent, _self or specified)empty
iframebooleanIf you're rendering Click to Pay in an iframe, this will need to be set to true.false

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 will be concatenated into a string, joined by colons: -> "INV1121:100.25:AUD"
  1. 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")

Response Verification (Purchases)

For purchases the response verification will consist of the response code, success indicator, amount, currency, transaction ID and the card token: -> "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:

messagestringAny messages relating to the transaction
amountintegerThe amount, as an integer
referencestringThe transaction reference
idstringThe Fat Zebra transaction ID
currencystringThe ISO-4217 3-letter currency code for the transaction
card_numberstringThe masked credit card number (e.g. 512345XXXXXXXX2346)
card_holderstringThe card holders name
card_expirydate (mm/yyyy)The card expiry date
card_typestringThe card type of the credit card used. Possible values are:
VISA, MasterCard
successfulbooleanIndicator of transaction success

Response Codes

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

2Declined - examine the message parameter for possible explanations
94Cancelled - the merchant clicked the Cancel button on the payment or checkout form
95Merchant Not Found - possible incorrect username
96Reference not unique
97Validation error - check the errors[] parameters for error messages
99Invalid Verification - the verification value does not match the parameters supplied
999Gateway error - an unknown error has occurred and the merchant should investigate with Fat Zebra Suppor