The following configuration documentation is for all forms of Click to Pay.

URLs

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

Environment	BASE URL
Sandbox	`https://paynow.pmnts-sandbox.io/v3/clicktopay`
Live	`https://paynow.pmnts.io/v3/clicktopay`

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/v3/clicktopay/[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.

Name	Type	Description
email	string	The email address for your user
mobile	string	The 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):

Name	Type	Description
username	string	The merchants Fat Zebra username
reference	string	The invoice number or order reference
currency	string (3 characters)	The ISO-4217 3-letter currency code for the transaction
amount	number	The 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)
hash	string	The hash is a MD5 hexdigest of a string compiled from the request parameters. See below (Verification Value Calculation) for more details.

Options

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

Name	Type	Description	Default
auth	boolean	If 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.	false
card_list_button_text	string	Sets the button text on the card list step of the flow. Default value is conditional based on `tokenizeOnly` value.	Confirm payment / Confirm payment method
css	string	HTTPS URL for external CSS - this must be a valid HTTPS URL, and serve up a valid CSS file. Depends on `css_signature`	empty
css_signature	string	HMAC-MD5 of the css URL with the shared secret to sign the request.	empty
display_name	string	Sets the merchant name displayed in the 'Save card for future use' text block when checking out with a new card.	merchant trading name
email	string	An email address to identify the user for Click to Pay. Used to perform an ID lookup as soon as the component loads. Can be passed at the same time as `mobile`.	empty
hide_confirm_button	boolean	Hides 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
hide_manual_entry_link	boolean	Hides the "Enter card details manually" link at the bottom of all Click to Pay screens.	false
iframe	boolean	If you're rendering Click to Pay in an iframe, this will need to be set to `true`.	false
mobile	string	A mobile number to identify the user for Click to Pay. Used to perform an ID lookup as soon as the component loads. Can be passed at the same time as `email`.	empty
return_path	string	The 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://....)	empty
return_target	string	The target for the form post (e.g. post back to `_parent`, `_self` or specified)	empty
shared_data	string	Comma-separated string that sets the shared data types specified in the 'Save card for future use' text block when checking out with a new card. Options are: card (=> "card details") billing (=> "billing address") email (=> "email") mobile (=> "mobile number")	card,billing,email,mobile
submit_payment_button_text	string	Sets the button text on the new card checkout and manual card entry steps of the flow. Default value is conditional based on `tokenizeOnly` value.	Pay Now / Add payment method
tokenize_only	boolean	Used to store just the card details themselves, without authorizing or capturing a purchase.	false

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:

The reference, currency, amount will be concatenated into a string, joined by colons:

https://paynow.pmnts.io/v3/clicktopay/samsbooks/INV1121/AUD/100.25/xxxxxxxxxxx -> "INV1121:100.25:AUD"

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:

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:

Name	Type	Description
message	string	Any messages relating to the transaction
amount	integer	The amount, as an integer
reference	string	The transaction reference
id	string	The Fat Zebra transaction ID
currency	string	The ISO-4217 3-letter currency code for the transaction
card_number	string	The masked credit card number (e.g. 512345XXXXXXXX2346)
card_holder	string	The card holders name
card_expiry	date (mm/yyyy)	The card expiry date
card_type	string	The card type of the credit card used. Possible values are: VISA, MasterCard
successful	boolean	Indicator of transaction success