V3 - Overview
The GreenPay Gateway provides a hosted payment page for merchants who wish to remove all PCI-DSS scope from their systems. This is known commercially as PayNow.
✔️ Please note that merchants and service providers are required to complete Self-Assessment Questionnaire A to adhere to PCI DSS Compliance.
Currently the hosted payment page supports three methods of implementation:
Standard Hosted Page (i.e. redirection from the merchants website to the payment page)
IFrame embedded page
Accounting platform payment page (for example Xero or Saasu)
The V3 UI looks like this, but it can be re-styled using the css parameter, documented below:
Usage
The data sent between the merchant and the GreenPay Gateway, and from the GreenPay Gateway to the merchant is sent in the request URL - to ensure that this has not been tampered with the payload includes a verification value, which is a signed-hash based on the payload values, using a shared secret between the merchant and the GreenPay Gateway.
This process has been closely modeled on the GreenPay Gateway Direct Post method - it is recommend you review this documentation for further details which may not be covered here.
URLs
There are two different URLs for the PayNow service - one for the Sandbox environment and one for the Live environment:
Sandbox
https://paynow.pmnts-sandbox.io/v3
Live
https://paynow.pmnts.io/v3
Request
In order to direct the customer to the hosted payment page the merchant's website should prepare the following URL and either use this as the redirect destination, or as the IFRAME source:
https://paynow.pmnts.io/v3/[username]/[reference]/[currency]/[amount]/[hash]
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):
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.
reference
string
The invoice number or order reference
username
string
The merchant's GreenPay username
Options
Provide any of the following as query parameters to specify display options - these are optional parameters:
iframe
boolean
Indicates whether to show the stripped-down iframe layout or not
false
show_email
boolean
Indicates whether to show and require the email field or not
true
show_extras
boolean
Indicates whether to display the invoice number and the amount to the customer
true
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
tokenize_only
boolean
If this is set the card will not be charged, and will only be tokenized for future use
false
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
button_text
string
Specifies the text to be displayed for the submit button (e.g. Pay Now or Submit)
Pay Now
return_target
string
When used in iframe mode (iframe=true) specifies where the target for the form post (e.g. post back to _parent, _self or speficied)
empty
postmessage
boolean
When used in iframe mode (iframe=true) specifies that the response should be sent using postMessage instead of redirecting
false
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.
For example, the CSS signature for https://example.com/example.css with a shared secret of "TEST" would be:
21387fed0d8f862e19a79b346eb710b8
Importantly: this hash is not a hash of the contents of the CSS file -- only the URL of the CSS file.
empty
logo_url
string
HTTPS URL for the merchant logo. This must be a valid HTTPS URL and serve up a valid image file.
empty
hide_button
boolean
Hides the button from the checkout form for when the checkout should be triggered by postMessage. Note this option is dependent on the v2 layout.
false
cards
string, comma separated
Specifies the whitelist or blacklist of accepted cards. If the string is prefixed with an exclamation mark (!) the cards listed will not be permitted. Possible values are: AMEX, JCB, VISA, MasterCard, Diners Examples !AMEX,JCB - disabled AMEX and JCB VISA,AMEX - enabled only VISA and AMEX Note if this field is present it is included in the end of the verification value string.
empty
surcharge
boolean
Specifies if a surcharge will be applied. Surcharge rates are set in the Surcharging section of the Merchant Dashboard. Note: if the surcharge field is set to true, “:true” must be appended in the verification hash.
false
hide_card_holder
boolean
Specifies if the card holder name field should be hidden
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 the GreenPay Gateway (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 the GreenPay Gateway)
The request received by the GreenPay Gateway will be verified with the following steps:
The reference, currency, amount, and if present, hide_card_holder and return_path will be concatenated into a string, joined by colons:
If hide_card_holder and/or return_path is not included, they will be omitted:
The value of this string will then be hashed with a HMAC-MD5, using the shared-secret known by the GreenPay Gateway and the merchant (please contact GreenPay Support if you are unsure of where to find this shared secret).
Response Verification (Purchases)
For purchases the response verification will consist of the response code, success indicator, amount, currency, transaction ID and the card token:
The response for purchases will also include the following:
message
string
Any messages relating to the transaction
amount
integer
The amount, as an integer
reference
string
The transaction reference
id
string
The GreenPay Gateway transaction ID
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, AMEX, JCB, Diners, Discover, China UnionPay, Unknown
successful
boolean
Indicator of transaction success
Response Verification (Tokenization)
For tokenization the response verification will consist of the response code, and the card token:
The response for tokenization will also include the following:
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
token
string
The token representing the card in the GreenPay Gateway systems
Response Codes
The following response codes are used when a redirect URL is provided:
1
Successful
2
Declined - examine the message parameter for possible explanations
94
Cancelled - the merchant clicked the Cancel button on the payment or checkout form
95
Merchant Not Found - possible incorrect username
96
Reference not unique
97
Validation error - check the errors[] parameters for error messages
99
Invalid Verification - the verification value does not match the parameters supplied
999
Gateway error - an unknown error has occurred and the merchant should investigate with Support
Testing
Standard GreenPay Gateway test procedures apply for the Hosted Payment Page. You can use our test card numbers to check the behaviour of the hosted payment page.
Last updated