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 |
|---|---|---|
| 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 |
| tokenize_only | boolean | Used to store just the card details themselves, without authorizing or capturing a purchase. | |
| 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 |
| 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 |
| iframe | boolean | If you're rendering Click to Pay in an iframe, this will need to be set to true. | false |
| hide_manual_entry_link | boolean | Hides the "Enter card details manually" link at the bottom of all Click to Pay screens. | 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:
- 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¤cy=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 |