Paymark Click APIs
API Endpoint
https://secure.paymarkclick.co.nz/apiIntroduction
This portal describes the Paymark Click APIs.
We recommend you read this Introduction section in full before looking at specific API details. The information in this section applies to all Paymark Click APIs.
The following APIs and services are described in this portal:
- Web Payments API:
-
Create a Paymark Click hosted web payment page (Standard Payment (“three party payment”)).
-
Securely tokenise card details for later use (an option under Standard Payment).
-
Create a secure token for future Online EFTPOS Autopay payments (an option under Standard Payment).
-
Process a secure transaction from the Merchant’s web site (Direct Post).
-
Track payments made on a specific card (marketing token using Standard Payment and Direct Post).
- Transaction Processing API: this set of REST APIs enables Merchant Hosted Payments, as well as “follow up” transactions, such as captures and refunds, against any payments and authorisations done through either the Web Payments API or the Transaction Processing API.
-
Merchant Hosted Payments: Process a “two party” card payment, authorisation or status check, or an Online EFTPOS payment.
-
Retrieve transaction details for a payment created through the Web Payments API or the Transaction Processing API.
-
Process a payment or authorisation transaction for a tokenised card (payment token or card token created via the Web Payments API or the Transaction Processing API).
-
Capture a prior authorisation created via the Web Payments API or the Transaction Processing API.
-
Cancel a prior authorisation that is no longer required.
-
Refund a transaction created via the Web Payments API or the Transaction Processing API.
- Token Management API:
-
Retrieve payment token details (including card tokens) created via the Web Payments API or the Transaction Processing API.
-
Update card token details, for example, card expiry date.
-
Delete card tokens that are out of date or no longer required.
You can sign up for a Click demo account here.
You can try out the Standard Payment integration option in our Web Payments sandbox.
Paymark Click also offers an Interactive Voice Response (IVR) to take payments and store cards for later use. The Click IVR can be connected to your own IVR or telephony platform. The Paymark Click IVR specification is available here.
The Click IVR is offered as a bespoke implementation. Should you with to integrate with the Click IVR, please contact Paymark on click@paymark.co.nz to discuss options.
End Points
The following end points are available for the Paymark Click APIs:
Production:
Web Payments: https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
Transaction Processing: https://secure.paymarkclick.co.nz/api/transaction
Retrieve Transaction: https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest
Retrieve Payment Tokens: https://secure.paymarkclick.co.nz/api/token/payment
Manage Card Tokens: https://secure.paymarkclick.co.nz/api/token/card
Remove Marketing Token: https://secure.paymarkclick.co.nz/api/token/merchanttoken/
Non-Production:
Web Payments: https://uat.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
Transaction Processing: https://uat.paymarkclick.co.nz/api/transaction
Retrieve Transaction: https://uat.paymarkclick.co.nz/api/webpayments/paymentservice/rest
Retrieve Payment Tokens: https://uat.paymarkclick.co.nz/api/token/payment
Manage Card Tokens: https://uat.paymarkclick.co.nz/api/token/card
Remove Marketing Token: https://uat.paymarkclick.co.nz/api/token/merchanttoken/
HTTP Headers
In addition to the headers that are required by the HTTP protocol, Paymark requires that you specify the Content and Accept headers.
The Content header is used to specify the content type that the Merchant application will pass in.
The Accept header is used to specify the content type that your client will accept.
Authentication
Authentication to the Click APIs is handled in one of two ways:
-
Passing in the username and password in the request body, or
-
Passing an encoded username and password in the HTTP header.
Refer to the individual APIs for information on what authentication model to use.
Authentication in the Request Body
Authentication is included in the transaction POST, in the username, password and account_id fields.
Example:
username=90127&
password=Paymark123&
account_id=700152
Authentication in the HTTP Header
Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request.
Format: username:password in base64 encoding.
Example:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
Web Payments ¶
Getting Started
Paymark Click is designed to take web-based card and Online EFTPOS payments by integrating into your website or eCommerce platform. The Web Payments API is a RESTful API.
How Web Payments Works
Integration Models
The Web Payments API supports two integration models:
-
Paymark Hosted Payment Page
-
Direct Post
You can select the option that best suits your integration requirements.
Both integration models support Online EFTPOS payments. Paymark Hosted Payment Page also supports Google Pay payments. Contact Paymark if you wish to enable Online EFTPOS or Google Pay.
Three Domain Secure (3DS) is fully supported under the Paymark Hosted Payment Page integration model. To use 3DS under Direct Post, additional development is required.
See also Merchant Hosted Transaction Processing for a further alternative.
Paymark Hosted Payment Page: This is the most commonly used option. This supports card, Online EFTPOS and Google Pay payments. This model is the easiest to implement out of all the options.
With each payment request, an encrypted secure URL is returned to provide a Paymark Click hosted web payment page for that transaction. This page contains appropriate merchant and transaction details and the Cardholder/Account Holder is required to enter their card or account information to proceed. Once the Cardholder/Account Holder submits valid card or account details and payment is processed and the transaction results are made available to the Merchant site/service.
As the payment page is hosted by Paymark, it minimises the Merchant’s PCI-DSS compliance requirements. The payment page also supports some CSS customisation to enable Merchant branding.
Full details are shown in the Paymark Hosted Payment Page section.
You can sign up for a demo account here. You can try out this integration option in our Web Payments sandbox.
Direct Post: This is designed to receive card or Online EFTPOS payer information in a direct URL post from any Merchant held payment page, without storing card or payer information in the Merchant’s system. This option reduces the Merchant’s PCI-DSS compliance requirements, while still giving the Merchant an option to use their own payment page if the Paymark Hosted Payment Page does not meet their needs. This is also the recommended method if the Merchant is using iFrames and does not require Three Domain Secure (3DS). Full details are shown in the Direct Post section.
If Direct Post is required, please talk to your Acquiring Bank. Your Acquiring Bank will assess your site and advise Paymark to enable this option accordingly.
Hosted Payment Page ¶
Overview
https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
The Hosted Payment Page service allows your web app to register a payment, authorisation, status check or tokenise request, which in turn will generate a unique URL that the application can use to load a secure payment page.
When setting up the card payment facility with your Acquiring Bank, you need to request the Gateway Hosted integration model. The Bank will then advise of your PCI compliance requirements.
The transactions available are:
-
Payment (purchase) (card, Online EFTPOS and Google Pay payments)
-
Authorisation (hold funds on a card for future charging)
-
Status check (validates card details with the issuing bank, no funds held or taken)
-
Tokenise card (store card for future payments without validating)
This service is a server to server communication method that validates all data posted to it. The payment request should be sent as a POST web request. All data should be provided in the body of the request formatted as a query string.
Once the request is received, the input will be validated and, if successful, a URL that can be used to access the Click hosted payment page will be returned. If an error occurs or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).
Transaction Flow for Paymark Hosted Payment Page
Transaction details may be retrieved by ID or by Merchant reference (Particular or Reference variables).
CSS customisation
The Click hosted payment page offers a base CSS page that you can download and customise to change the look and feel of the page: https://secure.paymarkclick.co.nz/webpayments/shared/assets/v3/css/base.css.
Once you have updated the CSS, you can upload this for approval via the Click Merchant Portal (Production portal, Demo portal). The Click team will review the CSS and publish it in that environment. Note: To ensure replication across all Click servers, please ensure each version of the CSS file has a different name e.g. include a date or version number in the file name.
Request Data
The following table shows the input fields that can be posted to the Hosted Payment Page API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
account_id | Your Paymark Click Account ID. | Required | Integer | N/A |
cmd | Defines the Web Payments integration service to use. Always use “_xclick” for a standard payment request. | Required | String | N/A |
amount | The transaction amount in NZD. Must be a positive value (more than zero) for purchase or authorisation requests. Ignored (and may be omitted) for “status check” requests. Ignored (but must be provided) for “tokenise” requests. | Required | Decimal | N/A |
type | Type of transaction requested, “purchase”, “authorisation” or “statuscheck”. Purchase is used to make a payment. Authorisation validates card details and holds funds on the card. Status check validates card details but does not hold any funds on the card; this is recommended for storing a card for future charges. A fourth option, “tokenise” is also available, however this does not validate card details. | Optional | String | N/A |
reference | Merchant defined value stored with the transaction. For Merchants accepting cards and Online EFTPOS, this should be a 12 character alphanumeric order identifier. This will appear on the Account Holder’s bank statement and is truncated at 12 characters, and any spaces or special characters will be removed. | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
return_url | The URL that the Cardholder/Account Holder will be sent to on completion of the payment. This must be a publicly accessible URL. Note: While this field is optional, this should be treated as required when the Return Option is set to Post to Return URL (see Two Return Options section) to ensure the Customer is returned to the Merchant web site. | Optional | String | 1024 |
display_customer_email | 0 or 1 as to whether to display the customer email receipt field. 0 = hide (default), 1 = display. | Optional | Integer | N/A |
store_payment_token | Determines if the Customer’s payment method will be stored (tokenised) when the transaction is successful. 0 = do not display option to store payment method (default), 1 = display option to store payment method for future use, 2 = store payment method without asking Customer (Customer must have opted into storing the payment method on the Merchant’s web site). If type is set to “tokenise”, the store_payment_token parameter will be ignored. | Optional | Integer | N/A |
token_reference | Merchant defined reference associated with the stored payment method (or card token). Allowed: alphanumeric, spaces, special characters @ # ’ " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
In addition, the following fields may be included for card transactions.
Name | Description | Required | Type | Length |
---|---|---|---|---|
merchant_token | 0 or 1 as to whether a marketing token should be generated and returned upon successful completion of the payment. 0 = do not generate a marketing token (default), 1 = generate and return marketing token. Note: If 1 is used, it is expected the Cardholder has opted in to creating a marketing token elsewhere on the Merchant web site. | Optional | Integer | N/A |
transaction_source | “MOTO” or “INTERNET” to indicate the source of the transaction. | Optional | String | N/A |
button_label | Customise the text used on the “MAKE PAYMENT” button. Text will always be displayed in capitals. Allowed: alphanumeric, spaces, special characters $ , - ’ ! ? . # | Optional | String | 20 |
Example:
POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1
Content-Type: application/x-www-form-urlencoded
account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
amount=10.00&
type=purchase&
reference=Reference&
particular=Particular&
display_customer_email=1&
store_payment_token=2&
token_reference=Account 12345&
button_label=PAY AND SAVE CARD
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference
POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1
Content-Type: application/x-www-form-urlencoded
account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
type=statuscheck&
reference=Reference&
particular=Particular&
display_customer_email=1&
store_payment_token=2&
token_reference=Account 12345&
button_label=SAVE CARD
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference
Note: Data is passed to the service as a URI query string so if a parameter contains URL punctuation characters it must be URL encoded. For example, reference=Ref?001 and particular=Part&001.
Response Data
Result Options
Result | Description |
---|---|
Success | https://< webpaymentsbaseurl >?q=<hosted payment page id> |
Failure | Returns REST error information in XML format. See REST Exceptions. |
Example:
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=5e274bfe878446a997e252b0c4189cc0
</string>
The Click hosted payment page URL returned will be wrapped in an XML element in string format. You will need to extract the URL and redirect the customer to it. The customer will then enter their payment details directly into the Click hosted payment page for processing.
Transaction Result
Transaction results, along with a set of other parameters, will be posted back to the Merchant’s return URL. At the same time, the Cardholder/Account Holder will be redirected back to the return URL.
For security and reliability reasons, Merchants are required to retrieve and validate the transaction results using the Retrieve Transaction function and not rely on the return post variables received in the return URL.
Note: Your return_url must have a valid SSL certificate to avoid the Cardholder/Account Holder’s browser prompting any security warning messages. The Click hosted payment page is a secure page. If the web page referenced in the return_url is not secure, most browsers prompt the Customer not to continue.
Output Fields for Post to Return URL
The following table shows the output fields to be posted back to the Return URL, along with a brief description of each.
Name | Description | Type | Length |
---|---|---|---|
TransactionId | Paymark Click defined unique transaction ID. | String | 8 |
Type | Transaction type (PURCHASE, AUTHORISATION, STATUS_CHECK, OE_PAYMENT, TOKENISE). | String | 50 |
AccountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
Status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
TransactionDate | Date and time when the transaction was processed. | Datetime | N/A |
BatchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
ReceiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
Amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
Reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
Particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
CardStored | When store_payment_token, store_card or store_card_without_input were used in the request, and the Customer paid using a card, this indicates whether or not the card was stored. false = not stored, true = stored. Will always be false for Online EFTPOS payments, even when store_payment_token has been used in the request. | Boolean | 10 |
ErrorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
ErrorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
PaymentToken | The token of the newly stored payment method. Only available if the store_payment_token variable was set to 1 or 2, and the Customer chose to store their payment method details, and the transaction was successful. Note: No token is created if the Customer pays using: * Online EFTPOS and the Merchant is not enabled for Online EFTPOS Autopay. *Google Pay. |
String | 100 |
PaymentTokenStatus | The status of the token request. The status is provided regardless of whether the token was created or not, so in the event a token could not be created, this is made clear to the Merchant. SUCCESS = payment token has been created (and PaymentToken will contain the token ID). MERCHANT_NOT_ENABLED = Customer selected a payment method for which the Merchant may not create tokens, for example, the Merchant is not enabled for Online EFTPOS Autopay and the Customer has paid using Online EFTPOS. USER_DECLINED = May appear when store_payment_token variable was set to 1. If Customer has paid using Online EFTPOS, and Customer has not selected Save OE Autopay, PaymentTokenStatus = USER_DECLINED and there is no PaymentToken. Note: If Customer has paid using a card, and Customer has not selected Save Card, CardStored variable shows as false and there is no PaymentToken or PaymentTokenStatus. ERROR = If (transaction) status = DECLINED, this means the Customer declined the Online EFTPOS payment. Or if there is another (transaction) status, this is an undefined issue when attempting to create the token. Contact Paymark for support. PROCESSING = awaiting Customer action for an Online EFTPOS payment. |
String | 100 |
TokenReference | Merchant defined reference associated with the stored payment method (or card token). Present if the Customer paid using a card. | String | 50 |
The following table shows output fields that may also be present for a card payment.
Name | Description | Type | Length |
---|---|---|---|
AuthCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
CardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
CardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
CardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
CardHolder | The Cardholder name entered into the Paymark Click hosted web payment page. | String | 100 |
MerchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchant_token variable was set to 1. | String | 100 |
CardToken | The token of the newly stored payment method, if the Customer paid using a card. Only available if the store_payment_token variable was set to 1 or 2, or store_card / store_card_without_input was set to 1, and the Customer chose to store their payment method details, and the transaction was successful. | String | 100 |
AcquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
Note on Transaction Status
The status field in the transaction response enables you to manage the Customer experience in your web site. For example:
-
SUCCESSFUL indicates the payment has been processed and you can fulfil the order.
-
DECLINED means the Bank has declined the payment so you may wish to offer the Customer an alternative payment method.
-
CANCELLED means the Customer cancelled out of the payment screen so you may wish to release any hold on goods that you have (pending payment).
Direct Post ¶
Overview
https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
The Direct Post service allows data from the Merchant hosted payment page to be securely sent to Paymark. Registering a payment request for Direct Post works in a similar way as Standard Payment. It allows the Merchant’s application to register a payment request and obtain a unique URL to which payment information can be posted.
When setting up the card payment facility with your Acquiring Bank, you need to request the Direct Post integration model. The Bank will then advise Paymark to enable Direct Post on your account. Direct Post requires a higher level of PCI compliance than Standard Payment. Your Bank will advise you of your specific requirements. For additional information, refer to the PCI DSS Self Assessment Questionnaires, A-EP information.
There are three options available for the transaction:
-
Payment (card and Online EFTPOS)
-
Authorisation (hold funds on a card)
-
Tokenise (store card for future payments).
For card payments, the Cardholder may also choose to store their card details (thus generating a card token) at the same time as making the payment.
A card token is ideal for websites or services that wish to collect card details for recurring billing purposes in a secure manner. This only applies to standard card types: Visa, MasterCard and American Express cards.
This service is implemented by encrypting the card number and expiry date and assigning it a unique token that can then be used to process future transactions. If using type “authorisation”, the card details are validated at the time the card is stored through creating an authorisation for the amount specified in the direct post request.
The transaction result is retrieved by unique reference Result_ID. Other transaction details may be retrieved by ID or by Merchant reference (Particular or Reference variables). See also Retrieve Transaction section.
This service is a server to server communication method that validates all data posted to it. The payment request should be sent as a POST web request. All data should be provided in the body of the request formatted as a query string.
Once the request is received, the input will be validated and, if successful, a URL that can be used to post payment details to Paymark Click will be returned. If an error occurs or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).
Transaction Flow
There are three stages to the Direct Post transaction:
- Merchant’s application registers the payment request and obtains a Direct Post URL.
- Merchant’s payment page collects payment information and posts to the Direct Post URL. Paymark then processes the transaction and returns a unique reference Result_ID.
- Merchant’s application retrieves the transaction result using the unique reference Result_ID.
Notes:
-
Your return_url must have a valid SSL certificate to avoid the Cardholder/Account Holder’s browser prompting any security warning messages.
-
Your site needs to be able to handle redirection to the Issuing Bank’s authentication site (Issuer ACS) if the Merchant is enabled for 3DS. C.f. 3DS with Direct Post Integration.

Direct Post Request Data
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
account_id | Your Paymark Click Account ID. | Required | Integer | N/A |
cmd | Defines the Web Payments integration service to use. Always use “_xdirect” for a Direct Post request. | Required | String | N/A |
type | Type of transaction requested, “purchase”, “authorisation” or “statuscheck”. Should be included if not using the account’s (account_id) default transaction type. Contact Paymark to confirm the default setting for this account_id. Purchase is used to make a payment on a card or using Online EFTPOS. Authorisation validates card details and holds funds on the card. Status check validates card details but does not hold any funds on the card; this is recommended for storing a card for future charges. A fourth option, “tokenise” is also available, however this does not validate card details so status check is recommended if the Merchant’s Acquiring Bank supports this. Contact Paymark to confirm if your Acquiring Bank supports status checks. | Optional | String | N/A |
amount | The transaction amount in NZD. Must be a positive value (more than zero) for purchase or authorisation requests. Ignored (and may be omitted) for status check requests. Ignored (but must be provided) for “tokenise” requests. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. For Merchants accepting cards and Online EFTPOS, this should be a 12 character alphanumeric order identifier. This will appear on the Account Holder’s bank statement and is truncated at 12 characters, and any spaces or special characters will be removed. | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
return_url | The URL that the Cardholder/Account Holder will be sent to on completion of the payment. This must be a publicly accessible URL. Note: While this field is optional, this should be treated as required to ensure the Result_Id can be returned to the Merchant and the Merchant can retrieve the transaction result to display to the Customer. | Optional | String | 1024 |
notification_url | Additional URL where the transaction response will be sent to. This must be a publicly accessible URL. | Optional | String | 1024 |
In addition, the following fields are included for card payments.
Name | Description | Required | Type | Length |
---|---|---|---|---|
merchant_token | 0 or 1 as to whether a marketing token should be generated and returned upon successful completion of the payment. 0 = do not generate a marketing token (default), 1 = generate and return marketing token. Note: If 1 is used, it is expected the Cardholder has opted in to creating a marketing token elsewhere on the Merchant web site. | Optional | Integer | N/A |
store_card_without_input | 0 or 1 as to whether the card should be tokenised upon a successful transaction. 0 = do not store (default), 1 = store card without giving the Cardholder an option to store their card. Note: It is expected the Cardholder has opted in to storing their card details elsewhere on the Merchant web site. | Optional | Integer | N/A |
transaction_source | “MOTO” or “INTERNET” to indicate the source of the transaction. Default value is “INTERNET”. | Optional | String | N/A |
token_reference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces, special characters @ # ’ " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1
Content-Type: application/x-www-form-urlencoded
account_id=700152&
username=90127&
password=Paymark123&
amount=10.00&
reference=Reference&
particular=Particular&
cmd=_xdirect&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference
Note: Data is passed to the service as a URI query string so if a parameter contains URL punctuation characters it must be URL encoded. For example, reference=Ref?001 and particular=Part&001.
Direct Post Request Result
Result Options
Result | Description |
---|---|
Success | The Direct Post URL returned will be wrapped in an XML element in string format. You will need to extract the Direct Post URL out and XML decode the URL before you pass it to your “browser object”. |
Failure | Returns REST error information in XML format. See REST Exceptions. |
Example:
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=5e274bfe878446a997e252b0c4189cc0
</string>
Post Payment Details
After a Direct Post URL has been obtained from above, a payment page on the Merchant’s web site can collect payment information and post it to the Direct Post URL. This may be card payment information or Online EFTPOS payment information. For specific requirements on the presentation and handling of Online EFTPOS payments, please also refer to the Online EFTPOS API specification or contact Paymark with any questions.
To process a card payment, the following fields are used for the post to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
card_number | Card number collected from Merchant’s payment page. | Required | String | 50 |
card_expiry_month | Expiry month of the card, in the format MM. | Required | String | 2 |
card_expiry_year | Expiry year of the card, in the format YY. | Required | String | 2 |
card_holder_name | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters - ’ | Optional | String | 256 |
card_csc | Card security code (CSC number). | Optional | String | 4 |
payment_method | Type of payment. Use CARD for card payments. | Required | String | N/A |
customer_email | Customer email address, if provided. Sends an email notification to the Customer to advise the transaction details and status. | Optional | String | 50 |
To process an Online EFTPOS payment, the following fields are used for the post to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
payer_id | Consumer’s personal identifier. See payerIdType and bankId Mapping table below for allowed payer ID types. See also Merchant Web Site Requirements for payerId validation rules. | Required | String | 128 |
payer_id_type | Defines the type of payerId that has been used. See payerIdType and bankId Mapping table below for allowed payer ID types. | Required | String | N/A |
bank | Consumer bank to which the payment request is sent. See payerIdType and bankId Mapping table below for allowed banks. | Required | String | N/A |
payment_method | Type of payment. Use OE for Online EFTPOS payments. | Required | String | N/A |
customer_email | Customer email address, if provided. Sends an email notification to the Customer to advise the transaction details and status. | Optional | String | 50 |
payerIdType and bankId Mapping
Supported Consumer Banks are:
-
ASB (bank = ASB)
-
Co-operative Bank (bank = COOPERATIVE)
-
Heartland (bank = HEARTLAND)
-
Westpac (bank = WESTPAC)
Each Consumer Bank can allow different types as the payerIdType. The table below shows what is allowed by each Consumer Bank (as specified in bankId).
Consumer Bank (bank) | Allowed Types (payerIdType) |
---|---|
ASB | MOBILE |
COOPERATIVE | MOBILE, CUSTOMERID |
HEARTLAND | MOBILE |
WESTPAC | MOBILE, WESTPAC1ID |
Examples:
POST https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=5e274bfe878446a997e252b0c4189cc0 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
card_number=4987654321098769&
card_expiry_month=05&
card_expiry_year=17&
card_holder_name=Mr John Smith&
card_csc=111&
payment_method=CARD
POST https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=5e274bfe878446a997e252b0c4189cc0 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
payer_id=ABC.123456789
payer_id_type=WESTPAC1ID
bank=WESTPAC
payment_method=OE
Output Fields
While the transaction is being processed, the Cardholder/Account Holder is redirected back to the Return URL that was in the transaction request, along with the Result_Id and a Transaction_No (for successful transactions).
Name | Description | Type |
---|---|---|
Result_Id | Identifier used to retrieve transaction details for successful transactions, or exception details for transactions with a REST Exception. | GUID |
Transaction_No | Identifier that is populated for successful transactions i.e. there were no REST Exceptions. Can be used to retrieve transaction details. | String |
Validating Transaction Result By Result_ID
After a Result_ID is returned from the previous step, the Merchant application can retrieve the transaction result.
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
account_id | Your Paymark Click Account ID. | Required | Integer | N/A |
result_id | Unique identifier for the Direct Post transaction, returned from the previous step after posting payment information. | Required | GUID | N/A |
Example:
GET https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/QueryDirectPostResultByResultId?
username=90127&
password=Paymark123&
account_id=700152&
result_id=e619459a-3c03-478f-b0c1-44a680ef87cc
HTTP/1.1
Validate Transaction Request Result
Result Options
Result | Description |
---|---|
Success | XML containing standard outputs for requested transaction information. |
Failure | Returns REST error information in XML format. See REST Exceptions. |
Success Result Parameters
Name | Description | Type | Length |
---|---|---|---|
Status | There are four possible statuses: PROCESSED, REJECTED, SESSION_EXPIRED, UNKNOWN. | String | 50 |
Message | Messages correspond to the status above: PROCESSED – “Transaction was processed”, REJECTED – “Transaction details failed validation”, SESSION_EXPIRED – “Session has expired”, UNKNOWN – “Unknown server error”. | String | N/A |
MerchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchant_token variable was set to 1. | String | 100 |
Transaction | Details of the transaction. See table below for UDT structure. | UDT | N/A |
Name | Description | Type | Length |
---|---|---|---|
TransactionId | Paymark Click assigned unique transaction ID. | String | 8 |
Type | Transaction type (PURCHASE, AUTHORISATION, STATUS_CHECK, REFUND, CAPTURE, OE_PAYMENT). | String | 50 |
AccountID | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
Status | Status of the transaction. UNKNOWN, SUCCESSFUL, DECLINED, BLOCKED, FAILED, INPROGRESS, CANCELLED. | String | 50 |
TransactionDate | Date and time when the transaction was processed. | Datetime | N/A |
BatchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
ReceiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
AuthCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
Amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
Reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
Particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
ErrorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
ErrorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
AcquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
The following table shows output fields that may also be present for a card payment.
Name | Description | Type | Length |
---|---|---|---|
CardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
CardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
CardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
CardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
CardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
CardToken | The token of the newly stored card, only available if the cardStored variable was set to 1 and the Cardholder chose to store their card details. | String | 100 |
TokenReference | Merchant defined reference associated with the stored card token. | String | 100 |
Merchant Hosted Transaction Processing ¶
Overview
https://secure.paymarkclick.co.nz/api/transaction/
The Transaction Processing API allows a Merchant to process a secure card or Online EFTPOS payment from their own web site (“two party payment”).
With this option, Merchants are able to utilise their own functions and processes to collect and store card details, and then make a direct server to server API call to process transactions via the Paymark Transaction Processing API. Merchants also have the option of bulk processing transactions with pre-collected Card details. Having the ability to collect and store card details, Merchants are required to meet full PCI-DSS compliance.
If Merchant Hosted Transaction Processing is required, please talk to your Acquiring Bank. Your Acquiring Bank will assess your site and advise Paymark to enable the option accordingly.
This option supports Online EFTPOS payments. Contact Paymark if you wish to enable Online EFTPOS.
Merchant Hosted Transaction Processing currently does not support Three Domain Secure (3DS).
The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.
Method Options
This API offers the following methods to process transactions:
Purchase with Card Details
This method allows Merchants to make a purchase transaction by passing in card data.
This method also allows this card to be stored (tokenised) and the token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address for the Cardholder. This field is for the Merchant’s use: Paymark Click does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. | Optional | String | 50 | |
cardNumber | Card number without spaces. Numeric format. | Required | String | 12-19 |
cardType | Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express and “QCARD” QCard. | Required | String | N/A |
cardExpiry | Card expiry date, in the format MMYY. E.g. 0518 for May 2018. Numeric format. | Required | String | 4 |
cardHolder | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters - ’ | Required | String | 256 |
cardCSC | Card security code found on the back of the card, in numeric format. If passed it will be used, else if left null or blank it will be ignored. Needs to be 4 digits for American Express, 3 digits for all other card types. | Optional | String | 3 or 4 |
merchantToken | Whether a marketing token should be registered and returned upon successful completion of the payment. 0 = do not register a marketing token (default), 1 = register and return a marketing token. | Optional | Integer | 1 |
storeCard | Whether the card should be stored and assigned a card token upon successful completion of the payment. 0 = do not store card (default), 1 = store card and return a card token. | Optional | Boolean | N/A |
tokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , + ? [ ] ( ) - _ | Optional | String | 50 |
transactionFrequency | Indicates whether this is a single or a recurring transaction. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Set to “Single” when charging a saved card, for example, the Customer has previously opted to save their Card then chooses to use this for a later purchase. For a Merchant initiated regular repeat purchase, for example, a magazine subscription, use “Recurring”. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Allowed: “Single”, “Recurring” or empty string i.e. “”. | Optional | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/purchase/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"cardNumber":"4987654321098769",
"cardType":"VISA",
"cardExpiry":"0517",
"cardHolder":"Mr John Smith",
"cardCSC":"111",
"storeCard":1,
"tokenReference":"TokenReference"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Details Exception | Card details passed do not pass card validation. |
One Dollar Auth Exception | Unable to obtain the $1 authorisation from the card details specified (if storing card data). |
For a full list of REST exceptions, refer to the REST Exceptions section.
Authorisation with Card Details
This method allows Merchants to make an authorisation transaction by passing in card data. An authorisation transaction holds funds on the card for charging at a later date, for example, if stock levels need to be checked before an order can be fulfilled. All authorisation transactions need to be either captured (charged) or cancelled (removes the hold).
This method also allows the card to be stored (tokenised) and the token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.
See also:
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address for the Cardholder. This field is for the Merchant’s use: Paymark Click does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. | Optional | String | 50 | |
cardNumber | Card number without spaces. Numeric format. | Required | String | 12-19 |
cardType | Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express and “QCARD” QCard. | Required | String | N/A |
cardExpiry | Card expiry date, in the format MMYY. E.g. 0518 for May 2018. Numeric format. | Required | String | 4 |
cardHolder | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters ’ - | Required | String | 256 |
cardCSC | Card security code found on the back of the card, in numeric format. If passed it will be used, else if left null or blank it will be ignored. Needs to be 4 digits for American Express, 3 digits for all other card types. | Optional | String | 3 or 4 |
merchantToken | Whether a marketing token should be registered and returned upon successful completion of the payment. 0 = do not register a marketing token (default), 1 = register and return a marketing token. | Optional | Integer | 1 |
storeCard | Whether the card should be stored and assigned a card token upon successful completion of the payment. 0 = do not store card (default), 1 = store card and return a card token. | Optional | Boolean | N/A |
tokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , | Optional | String | 50 |
transactionFrequency | Indicates whether the transaction is a single or a recurring transaction. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Set to “Single” when charging a saved card, for example, the Customer has previously opted to save their Card then chooses to use this for a later purchase. For a Merchant initiated regular repeat purchase, for example, a magazine subscription, use “Recurring”. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Allowed: “Single”, “Recurring” or empty string i.e. “”. | Optional | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/authorisation/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"cardNumber":"4987654321098769",
"cardType":"VISA",
"cardExpiry":"0517",
"cardHolder":"Mr John Smith",
"cardCSC":"111",
"storeCard":1,
"tokenReference":"TokenReference"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Details Exception | Card details passed do not pass card validation. |
Payment Details Exception | Authorisation transaction details do not pass validation. |
One Dollar Auth Exception | Unable to obtain the $1 authorisation from the card details specified (if storing card data). |
For a full list of REST exceptions, refer to the REST Exceptions section.
Status Check with Card Details
This method allows Merchants to make a status check transaction by passing in card data. A status check validates the card with the Issuer without the need to hold funds on the card. Not all Acquiring Banks support status checks: contact Paymark to confirm if your Acquiring Bank supports status checks.
The primary use for a status check is to store the card for future transactions. The card is stored (tokenised) and the token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.
See also:
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | Ignored (and may be omitted) for status check requests. | Optional | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address for the Cardholder. This field is for the Merchant’s use: Paymark Click does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. | Optional | String | 50 | |
cardNumber | Card number without spaces. Numeric format. | Required | String | 12-19 |
cardType | Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express and “QCARD” QCard. | Required | String | N/A |
cardExpiry | Card expiry date, in the format MMYY. E.g. 0518 for May 2018. Numeric format. | Required | String | 4 |
cardHolder | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters ’ - | Required | String | 256 |
cardCSC | Card security code found on the back of the card, in numeric format. While this is an optional field from the API perspective, the Issuer may need this to process the transaction so should be treated as required. Needs to be 4 digits for American Express, 3 digits for all other card types. | Optional | String | 3 or 4 |
merchantToken | Whether a marketing token should be registered and returned upon successful completion of the payment. 0 = do not register a marketing token (default), 1 = register and return a marketing token. | Optional | Integer | 1 |
storeCard | Whether the card should be stored and assigned a card token upon successful completion of the payment. 0 = do not store card (default), 1 = store card and return a card token. | Optional | Boolean | N/A |
tokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , | Optional | String | 50 |
transactionFrequency | Indicates whether the transaction is a single or a recurring transaction. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Set to “Single” when charging a saved card, for example, the Customer has previously opted to save their Card then chooses to use this for a later purchase. For a Merchant initiated regular repeat purchase, for example, a magazine subscription, use “Recurring”. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Allowed: “Single”, “Recurring” or empty string i.e. “”. | Optional | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/statuscheck/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"reference":"Reference",
"particular":"Particular",
"cardNumber":"4987654321098769",
"cardType":"VISA",
"cardExpiry":"0517",
"cardHolder":"Mr John Smith",
"cardCSC":"111",
"storeCard":1,
"tokenReference":"TokenReference"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Details Exception | Card details passed do not pass card validation. |
Payment Details Exception | Status check transaction details do not pass validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Store Card Details without Issuer Validation
This method allows Merchants to store the card for future payments, without validating card details with the card issuer or holding funds on the card. This method exists for historical purposes and is useful for storing card details if the Merchant’s Acquiring Bank does not support status checks. Contact Paymark to confirm if your Acquiring Bank supports status checks.
The recommended method is now Status Check, which validates card details without holding funds on the card.
A card token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.
See also:
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
cardNumber | Card number without spaces. Numeric format. | Required | String | 12-19 |
cardType | Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express and “QCARD” QCard. | Required | String | N/A |
cardExpiry | Card expiry date, in the format MMYY. E.g. 0518 for May 2018. Numeric format. | Required | String | 4 |
cardHolder | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters ’ - | Required | String | 256 |
tokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces. | Optional | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/token/card HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"cardNumber":"4987654321098769",
"cardType":"VISA",
"cardExpiry":"0517",
"cardHolder":"Mr John Smith",
"tokenReference":"TokenReference"
}
Output Fields
The store card details transaction processing method has the response outputs as described below.
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
cardToken | The token of the newly stored card | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
tokenReference | Merchant defined reference associated with the stored card token. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Details Exception | Card details passed do not pass card validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Online EFTPOS Payment
This method allows Merchants to send a payment request to a Customer using Online EFTPOS.
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. This is used on the Consumer’s bank statement and will be truncated at 12 characters. We recommend a maximum of 12 characters is used in this field. Allowed: alphanumeric, space, hyphen. | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address for the Cardholder. This field is for the Merchant’s use: Paymark Click does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. | Optional | String | 50 | |
payerId | Consumer’s personal identifier. See payerIdType and bankId Mapping table below for allowed payer ID types. See also Merchant Web Site Requirements for payerId validation rules. | Required | String | 15 |
payerIdType | Defines the type of payerId that has been used. See payerIdType and bankId Mapping table below for allowed payer ID types. | Required | String | N/A |
bank | Consumer bank to which the payment request is sent. See payerIdType and bankId Mapping table below for allowed banks. | Required | String | N/A |
payerIdType and bankId Mapping
Supported Consumer Banks are:
-
ASB (bank = ASB)
-
Co-operative Bank (bank = COOPERATIVE)
-
Heartland (bank = HEARTLAND)
-
Westpac (bank = WESTPAC)
Each Consumer Bank can allow different types as the payerIdType. The table below shows what is allowed by each Consumer Bank (as specified in bankId).
Consumer Bank (bank) | Allowed Types (payerIdType) |
---|---|
ASB | MOBILE |
COOPERATIVE | MOBILE, CUSTOMERID |
HEARTLAND | MOBILE |
WESTPAC | MOBILE, WESTPAC1ID |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/oepayment HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"payerId": "0210123456",
"payerIdType": "MOBILE",
"bank": "ASB"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Outputs
Most of the transaction processing methods in this section have a standard set of response outputs as described below. Note: The Store Card Details without Issuer Validation method has a subset of response outputs.
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click assigned unique transaction ID. | String | 8 |
originalTransactionId | Used in refund, capture and cancellation transactions. Contains the transaction ID for the related (authorisation or payment) transaction. | String | 8 |
type | Transaction type (PURCHASE, AUTHORISATION, STATUS_CHECK, OE_PAYMENT). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
surcharge | Surcharge amount, if a card surcharge has been enabled. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). Will be “UNKNOWN” for an Online EFTPOS payment. | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. Will be empty for an Online EFTPOS payment. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. Will be empty for an Online EFTPOS payment. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. Will be empty for an Online EFTPOS payment. | String | 100 |
cardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. Will be false for an Online EFTPOS payment. | Boolean | 10 |
cardToken | The token of the newly stored card, only available if the cardStored variable was set to 1 and the Cardholder chose to store their card details. Will be NULL for an Online EFTPOS payment. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
tokenReference | Merchant defined reference associated with the stored card token. Will be NULL for an Online EFTPOS payment. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. Will be empty for an Online EFTPOS payment. | String | 100 |
payerId | Consumer’s personal identifier for Online EFTPOS payments. Will be NULL for card transactions. | String | 100 |
payerIdType | Type of payerId that was used. Will be NULL for card transactions. | String | 100 |
bank | Consumer bank to which the Online EFTPOS payment request was sent. Will be NULL for card transactions. | String | 100 |
Three Domain Secure ¶
Overview
Three Domain Secure (3DS) is a payment card industry standard for authenticating a Cardholder performing an online purchase and is designed to provide greater online transaction security for both the Cardholder and the Merchant. It is marketed by Mastercard as “Mastercard Securecode” and by Visa as “Verified by Visa” (VbV).

With 3DS transactions, a Cardholder may be asked to authenticate himself during an online transaction by entering Cardholder specific information, such as a pre-configured password or one time password, which is authenticated by the Cardholder’s Issuing Bank.
3DS also provides level of chargeback protection for participating Merchants under certain conditions.
Enabling 3DS
If you wish to enable 3DS, please contact your Acquirer Bank for 3DS enrolment. Your Acquirer Bank will complete your enrolment and send Paymark an activation notice with all the required information.
Please note, if you use 3DS your website and integration method must support the use of sessions and cookies. For some newer web browsers, this means you may not be able to host the payment page in an iFrame.
3DS with Standard Payment Integration
For Standard Payment integration, Click handles the entire flow of the 3DS process and no specific development is required for 3DS.
3DS with Direct Post Integration
For Direct Post integration, Click handles the flow of the 3DS process. However, Cardholders will be redirected away from your website to the Issuing Bank’s authentication site to complete their card verification. The Cardholder will then be redirected back to your site. You need to make sure your website can handle this redirection in order for 3DS to work smoothly.
How 3DS works with Direct Post

Between the Direct Post Request Result and Post Payment Details steps, the Merchant is sent a HTML payload that can be used to invoke the Cardholder redirection to the Issuer’s 3DS authentication flow (Issuer ACS).
3DS with Merchant Hosted Integration
3DS is not supported with Direct API integration via methods detailed under Merchant Hosted Transaction Processing. If you wish to implement this function, contact Paymark for further consultation.
Possible Errors and 3DS Details
For both Standard Payment integration and Direct Post integration, Click handles 3DS processing. There are no additional inputs and outputs. Possible 3DS errors are detailed in error codes 270-272 under Response Codes and Messages.
You can see 3DS information for any transaction under “Transactions Details” in the Click Merchant Portal. You can see whether 3DS was used and what the authentication result was.

Retrieve Transaction ¶
Overview
Once the transaction has been processed the results can be retrieved and validated using one of the methods described below. Options are to retrieve the transaction by (Paymark) ID, or by (Merchant) reference or particular.
The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.
Method Options
https://secure.paymarkclick.co.nz/api/transaction/search/<transactionID>
Transaction requests should be sent as a GET web requests. Input data should be provided as part of the URL request. Once the request is received the input will be validated and, if successful, response will be returned in JSON format with body containing information for the requested transaction.
Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request.
If an error occurs, or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).
Retrieve Transaction by Transaction ID
Input
Transaction ID is passed in as part of the URL and no other inputs are required for the request.
Example:
GET https://secure.paymarkclick.co.nz/api/transaction/search/P170310001234567 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Result Options
Result | Description |
---|---|
Success | 200 with body containing output elements below. |
Failure | See exceptions and errors below. |
Output Fields
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click defined unique transaction ID for this transaction. | String | 8 |
originalTransactionId | Used in refund, capture and cancellation transactions. Contains the transaction ID for the related (authorisation or payment) transaction. | String | 8 |
type | Transaction type (PURCHASE, AUTHORISATION, STATUS_CHECK, REFUND, CAPTURE, CANCELLATION, OE_PAYMENT). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
surcharge | If the Merchant has added a surcharge % to this transaction, this is the surcharge amount for this transaction. Note: Contact Paymark to configure a surcharge for your Merchant account. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 50 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 50 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, DINERS_CLUB, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the Paymark Click hosted web payment page. | String | 100 |
cardStored | Whether or not the card was stored, false = not stored, true = stored. Will always be false for Online EFTPOS payments. | Boolean | 10 |
cardToken | Payment token ID if a payment (or card) token was used for this transaction and the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 510 |
tokenReference | Merchant defined reference associated with the payment (or card) token used in this transaction, if the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 50 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Consumer’s personal identifier for Online EFTPOS payments. | String | 100 |
payerIdType | Type of payerId that was used for Online EFTPOS payments. | String | 100 |
bank | Consumer bank to which the Online EFTPOS payment request was sent. | String | 100 |
authenticationReference | Transaction ID for 3DS 2. Can be used as threeDSRequestorInformation.priorAuthenticationInfo.reference in future 3DS 2 transactions for this cardholder. | String | 50 |
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
404 Not Found | 5019 | Transaction not found. |
401 Unauthorised | 3000 | Authentication error. Username and/or Password are incorrect. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
Search for Transactions
Input Fields
Name | Description | Required | Type | Length |
---|---|---|---|---|
startDate | Starting date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. | Required | Datetime | N/A |
endDate | Ending date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. | Required | Datetime | N/A |
reference | Reference value which transaction reference should match exactly to be included in the result. | Optional | String | 50 |
particular | Particular value which transaction reference should match exactly to be included in the result. | Optional | String | 50 |
clientAccountId | Client Account ID under which transaction should be searched for. If empty, method will search for all transactions under the merchant. | Optional | Integer | N/A |
Example:
GET https://secure.paymarkclick.co.nz/api/transaction/search?
startDate=2017-08-01T00:00:00&
endDate=2017-08-02T00:00:00&
reference=Click-Test-Reference&
particular=Click-Test-Particular&
clientAccountId=7012345
HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Result Options
Result | Description |
---|---|
Success | 200 with body containing up to 100 transactions. For each returned transaction, details are the same as the output fields documented in Retrieve transaction by Transaction ID, ordered by transaction date in descending order. Note if search result covers more than 100 records, only the latest 100 records are returned. Therefore, an appropriate combination of parameters should be considered to restrict the search range. |
Failure | See exceptions and errors below. |
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
400 Bad Request | 7004 | Start date cannot be greater than End date, please consult the payment web service integration manual. |
400 Bad Request | 7005 | Date range greater than 1 year, please restrict the date range, please consult the payment web service integration manual. |
400 Bad Request | 7002 | Reference cannot contain more than 50 characters, please consult the payment web service integration manual. |
400 Bad Request | 5019 | Particular cannot contain more than 50 characters, please consult the payment web service integration manual. |
400 Bad Request | 6023 | Client Account ID provided is not valid. |
401 Unauthorised | 3000 | Authentication error. Username and/or Password are incorrect. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
Capture Transaction ¶
Overview
https://secure.paymarkclick.co.nz/api/transaction/
The Transaction Processing API allows a Merchant to capture (receive funds for) a previously created successful card authorisation transaction.
The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.
Capture Transaction
This method allows Merchants to capture the funds from a previously made, successful, card authorisation transaction. In order to perform a capture you will need to pass the original (authorisation) transaction ID and the amount to capture. This can be less than or equal to, but never more than, than the original authorisation transaction amount.
See also:
Notes:
-
All authorisations need to be finalised, either through a capture or a cancellation.
-
If an authorisation has already been cancelled, it cannot be captured.
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
originalTransactionId | The Paymark transaction ID of the authorisation transaction to be captured. Alphanumeric format. | Required | String | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
conditionIndicator | Indicates whether this is the last capture to be performed against the authorisation (“final”), or whether additional capture transactions are expected (“partial”). Designed for cases the order is fulfilled in parts, and the Customer is charged as each part is fulfilled. | Optional | String | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address to send receipt to. If not required, leave blank. | Optional | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/capture HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"originalTransactionId":"P160110000014131",
"amount":10.00,
"conditionIndicator":"final",
"reference":"Reference",
"particular":"Particular"
}
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click assigned unique transaction ID. | String | 8 |
originalTransactionId | Contains the transaction ID of the initial transaction, only populated in a capture, refund or cancellation transaction. | String | 8 |
type | Transaction type (CAPTURE). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
surcharge | Surcharge amount, if a card surcharge has been enabled. | Decimal | 20 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
cardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
cardToken | Payment token ID if a payment (or card) token was used for this transaction and the payment method associated with this token is a card. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
tokenReference | Merchant defined reference associated with the payment (or card) token used in this transaction, if the payment method associated with this token is a card. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Not applicable for capture transactions. | String | 100 |
payerIdType | Not applicable for capture transactions. | String | 100 |
bank | Not applicable for capture transactions. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Payment Details Exception | Capture transaction details do not pass validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Cancellation Transaction ¶
Overview
https://secure.paymarkclick.co.nz/api/transaction/
The Transaction Processing API allows a Merchant to cancel a card authorisation when this authorisation is no longer needed and the funds will never be captured.
The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.
Cancellation Transaction
This method allows Merchants to cancel a previously made, successful, authorisation transaction that is no longer required, for example, because the order cannot be fulfilled. All authorisations need to be finalised, either through a Capture or a cancellation. In order to perform a cancellation you will need to pass the original (authorisation) transaction ID.
Note: If an authorisation has already been captured, it cannot be cancelled.
See also:
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
originalTransactionId | The Paymark transaction ID of the authorisation transaction to be captured. Alphanumeric format. | Required | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/cancellation HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"originalTransactionId":"P160110000014131"
}
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click assigned unique transaction ID. | String | 8 |
originalTransactionId | Contains the transaction ID of the initial transaction, only populated in a capture, refund or cancellation transaction. | String | 8 |
type | Transaction type (CANCELLATION). | String | 50 |
accountID | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
cardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
cardToken | Payment token ID if a payment (or card) token was used for this transaction and the payment method associated with this token is a card. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
tokenReference | Merchant defined reference associated with the payment (or card) token used in this transaction, if the payment method associated with this token is a card. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Not applicable for cancellation transactions. | String | 100 |
payerIdType | Not applicable for cancellation transactions. | String | 100 |
bank | Not applicable for cancellation transactions. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Payment Details Exception | Cancellation transaction details do not pass validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Refund Transaction ¶
Overview
https://secure.paymarkclick.co.nz/api/transaction/
The Transaction Processing API allows a Merchant to refund a previously created successful purchase or capture transaction.
The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.
Refund Transaction
This method allows Merchants to refund a previously made, successful, purchase or capture transaction. In order to perform a refund you will need to pass the original transaction ID and the amount to refund. This can be less than or equal to, but never more than, than the original purchase or capture transaction amount. Note: You should only attempt to refund a transaction that is less than six months old: there may be issues with the correct Cardholder receiving funds for transactions older than six months.
See also:
Input Fields
The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
originalTransactionId | The Paymark transaction ID of the transaction to refund. Alphanumeric format. | Required | String | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address to send receipt to. If not required, leave blank. | Optional | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/refund HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"originalTransactionId":"P160110000014131",
"amount":10.00,
"reference":"Reference",
"particular":"Particular"
}
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click assigned unique transaction ID. | String | 8 |
originalTransactionId | Contains the transaction ID of the initial transaction, only populated in a capture, refund or cancellation transaction. | String | 8 |
type | Transaction type (REFUND). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
surcharge | Surcharge amount, if a card surcharge has been enabled. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
cardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
cardToken | Payment token ID if a payment (or card) token was used for this transaction and the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
tokenReference | Merchant defined reference associated with the payment (or card) token used in this transaction, if the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Consumer’s personal identifier for Online EFTPOS payments. | String | 100 |
payerIdType | Type of payerId that was used. | String | 100 |
bank | Consumer bank to which the Online EFTPOS payment request was sent. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Payment Details Exception | Refund transaction details do not pass validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Payment Token Transaction Processing ¶
Overview
https://secure.paymarkclick.co.nz/api/transaction/
Click supports two types of tokens for financial transactions:
-
Payment token, which supports multiple payment methods, including card payments and Online EFTPOS payments.
-
Card token, a deprecated feature than can be used for cards only.
This section covers both types of tokens, and the functions available with each. If building a new integration with Click, we recommend using payment tokens to build longevity into your integration.
The Token Processing API allows a Merchant to use payment (card or Online EFTPOS) tokens to process transactions. A payment token allows Merchants to initiate a payment without requiring the Cardholder to enter any additional information (for card tokens), or Account Holder to approve the payment (for Online EFTPOS tokens).
A payment token can be created using the Paymark Click hosted web payment page (using the Standard Payment integration model). A payment token can be created for both card and Online EFTPOS payment methods. Cards that can be tokenised are: Visa, MasterCard, American Express and Q Card cards.
A card token may also be created through a Direct Post or Merchant Hosted payment page, the Click IVR, or the Click Merchant Portal.
This token processing feature can also be built into systems to create an automated, flexible processing system to suit business processes, for example, billing cycles.
This function is implemented by encrypting the payment details via an initial transaction and assigning it a unique token number which can then be used to process future transactions.
For information on managing existing payment or card tokens, see the Manage Tokens section.
The Token Processing API is a RESTful API over HTTP, with a JSON payload.
Method Options
This API offers the following methods to process token transactions:
Purchase with Payment (or Card) Token
This method allows Merchants to make a purchase transaction using previously stored payment method data. To use this method, the Merchant must have already stored the payment method with Paymark and have an existing payment (or card) token.
Input Fields
The token identifier to be charged is passed in as part of the URL. The following table shows the other input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address to send receipt to. If not required, leave blank. | Optional | String | 50 | |
transactionFrequency | Applies to tokens created for card payments. Indicates whether this is a single or a recurring transaction. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Set to “Single” when charging a saved card, for example, the Customer has previously opted to save their Card then chooses to use this for a later purchase. For a Merchant initiated regular repeat purchase, for example, a magazine subscription, use “Recurring”. Allowed: “Single”, “Recurring” or empty string i.e. “”. | Optional | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/purchase/OE.1234567890 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular"
}
POST https://secure.paymarkclick.co.nz/api/transaction/purchase/6971410 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"transactionFrequency":"Single"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Token Exception | The card token passed is not found or is invalid. This manifests as a REST exception 400. |
Payment Details Exception | Payment details do not pass validation. |
OE Autopay Token Not Found | Merchant has attempted a transaction using a token ID that has been removed in Click. The Merchant should delete their record of this token. C.f. Online EFTPOS Autopay Transaction Flow. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Authorisation with Payment (or Card) Token
This method allows Merchants to make an authorisation transaction using previously stored card data. To use this method, the Merchant must have already stored the card with Paymark and have an existing payment (or card) token.
Input Fields
The card token identifier (for the card to be authorised) is passed in as part of the URL. The following table shows the other input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Paymark issued Account ID. | Required | Integer | N/A |
amount | The transaction amount in NZD. Must be a positive value. | Required | Decimal | N/A |
reference | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
Email address to send receipt to. If not required, leave blank. | Optional | String | 50 | |
transactionFrequency | Indicates whether this is a single or a recurring transaction. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Set to “Single” when charging a saved card, for example, the Customer has previously opted to save their Card then chooses to use this for a later purchase. For a Merchant initiated regular repeat purchase, for example, a magazine subscription, use “Recurring”. If not passed in or empty, it will take the default frequency from the Paymark Click account setting. Allowed: “Single”, “Recurring” or empty string i.e. “”. | Optional | String | N/A |
Example:
POST https://secure.paymarkclick.co.nz/api/transaction/authorisation/6971410 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"transactionFrequency":"Single"
}
Output Fields
Standard response outputs are detailed in the Outputs section.
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Token Exception | The card token passed is not found or is invalid. This manifests as a REST exception 400. |
Payment Details Exception | Authorisation details do not pass validation. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Outputs
All token transaction processing methods have a standard set of response outputs as described below.
Output Fields
Name | Description | Type |
---|---|---|
transactionResult | Details of the transaction. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click assigned unique transaction ID. | String | 8 |
originalTransactionId | Used in refund, capture and cancellation transactions. Contains the transaction ID for the related (authorisation or payment) transaction. | String | 8 |
type | Transaction type (PURCHASE, AUTHORISATION). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
surcharge | Surcharge amount, if a card surcharge has been enabled. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the secure payment page. | String | 100 |
cardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
cardToken | Payment token ID if a payment (or card) token was used for this transaction and the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
tokenReference | Merchant defined reference associated with the payment (or card) token used in this transaction, if the payment method associated with this token is a card. Note: The Merchant can use the Merchant Portal to see payment token details when the payment method (associated with the token) is Online EFTPOS. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Will be NULL for card token transactions. | String | 100 |
payerIdType | Will be NULL for card token transactions. | String | 100 |
bank | Will be NULL for card token transactions. | String | 100 |
Manage Payment and Card Tokens ¶
Overview
https://secure.paymarkclick.co.nz/api/token/payment
https://secure.paymarkclick.co.nz/api/token/card
A payment token is ideal for websites or services that need to securely store payment details for future purchases or recurring billing purposes. See also Token Transaction Processing.
The Token Management API is available for managing existing stored tokens: payment method details (card and Online EFTPOS) can be retrieved, details for card tokens can be updated, and card tokens can be removed.
The Token Management API is a RESTful API over HTTP, with a JSON payload.
Method Options
This API offers the following methods to manage card tokens:
-
Update card token information (for card tokens only)
-
Remove a card token (for card tokens only)
Retrieve Payment Method Details Using Payment Token
This method provides the functionality to retrieve the details of a stored payment method (card or Online EFTPOS) using the token identifier.
Only partial details for the payment method will be retrieved, and this is not sufficient to perform a transaction. The purpose of this method is for information only.
Input Fields
The token identifier is passed in as part of the URL.
Example:
GET https://secure.paymarkclick.co.nz/api/token/payment/OE.1234567890 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
Name | Description | Type | Length |
---|---|---|---|
tokenType | Indicates the payment method this token is for. Options are CARD and OE. | String | N/a |
token | Token identifier. | String | 100 |
tokenReference | Merchant defined reference associated with the stored payment token. | String | 100 |
tokenDetails | Details of the payment method. See table below for UDT structure. | UDT | N/a |
Token Details for Card Payment Method
Name | Description | Type | Length |
---|---|---|---|
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 50 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 100 |
cardHolder | The Cardholder name initially collected from the secure payment page. | String | 100 |
cardExpiry | Expiry date of the card, in format MMYY. | String | 100 |
Token Details for Online EFTPOS Payment Method
Name | Description | Type | Length |
---|---|---|---|
payerId | Consumer’s personal identifier (with the bank). | String | 50 |
bank | Consumer bank this payment token is for. | String | 100 |
payerIdType | The type of payerId that has been used, for example, mobile number. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Token Not Found | The payment token passed in is not found or is invalid. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Retrieve Card Details Using Card Token
This method provides the functionality to retrieve the details of a stored card using the token identifier, when the card was stored using the “store card” method.
Only partial details for the card will be retrieved, and this is not sufficient to perform a transaction. The purpose of this method is for information only.
Input Fields
The token identifier is passed in as part of the URL.
Example:
GET https://secure.paymarkclick.co.nz/api/token/card/6971410 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
Name | Description | Type |
---|---|---|
cardDetails | Details of the card. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
cardToken | Token identifier for the card. | String | 100 |
tokenReference | Merchant defined reference associated with the stored card token. | String | 100 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 50 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 100 |
cardHolder | The Cardholder name initially collected from the secure payment page. | String | 100 |
cardExpiry | Expiry date of the card, in format MMYY. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
Card Token Not Found | The card token passed in was not found or is invalid. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Retrieve Payment Method Details Using Token Reference
This method retrieves the details of all stored payment methods with the token reference that matches the parameter passed. The token type (card or OE) may be passed as an optional parameter.
Only partial information is returned, and this is not sufficient to perform a transaction. The purpose of this method is for information only.
Input Fields
The following table shows the input fields that can be posted to the Token Management API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
tokenReference | URL encoded value of the token reference the returned tokens must have. This is not case sensitive. If left empty, payment tokens with no token reference will be returned. | Required | String | 50 |
tokenType | The type of payment token to be searched: CARD or OE. | Optional | String | N/A |
startDate | Earliest date the token was created (inclusive of datetime specified). | Optional | Datetime | N/A |
endDate | Latest date the token was created (inclusive of datetime specified). | Optional | Datetime | N/A |
Example:
GET https://secure.paymarkclick.co.nz/api/token/payment/?tokenReference=TokenReference&tokenType=OE HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
Name | Description | Type |
---|---|---|
tokenDetails Array | Details of the payment tokens with this token reference. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
tokenType | Indicates the payment method this token is for. Options are CARD and OE. | String | N/a |
token | Token identifier. | String | 100 |
tokenReference | Merchant defined reference associated with the stored payment token. | String | 100 |
tokenDetails | Details of the payment method. See table below for UDT structure. | UDT | N/a |
Token Details for Card Payment Method
Name | Description | Type | Length |
---|---|---|---|
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 50 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 100 |
cardHolder | The Cardholder name initially collected from the secure payment page. | String | 100 |
cardExpiry | Expiry date of the card, in format MMYY. | String | 100 |
Token Details for Online EFTPOS Payment Method
Name | Description | Type | Length |
---|---|---|---|
payerId | Consumer’s personal identifier (with the bank). | String | 50 |
bank | Consumer bank this payment token is for. | String | 100 |
payerIdType | The type of payerId that has been used, for example, mobile number. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Retrieve Card Details Using Token Reference
This method provides the functionality to retrieve the details of all stored cards with the token reference that matches the parameter passed, when the cards were stored using the “store card” method.
Only partial information is returned, and this is not sufficient to perform a transaction. The purpose of this method is for information only.
Input Fields
The following table shows the input fields that can be posted to the Token Management API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
tokenReference | URL encoded value of the token reference the returned cards must have. This is not case sensitive. | Required | String | 50 |
Example:
GET https://secure.paymarkclick.co.nz/api/token/card/?tokenReference=TokenReference HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
Name | Description | Type |
---|---|---|
cardDetails Array | Details of the cards with this token reference. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
cardToken | Token identifier for the card. | String | 100 |
tokenReference | Merchant defined reference associated with the stored card token. | String | 100 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardHolder | The Cardholder name initially collected from the secure payment page. | String | 100 |
cardExpiry | Expiry date of the card, in format MMYY. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service is not available to you. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Update Card Token Information
This method allows selected information for existing tokenised cards to be updated. The token of the card should be passed in to locate the card. This method is only available for tokens created using the “store card” method. Payment tokens cannot be used with this method.
The card attributes that can be updated are:
-
Card expiry date
-
Card token reference
-
Name on the card
The response will return the current value after any update made to the token.
Note: The CVV is not required when the card expiry date is updated.
Input Fields
The following table shows the input fields that can be posted to the Token Management API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
cardToken | Token of the card to be found. In numeric format. | Required | String | 50 |
cardExpiry | Expiry date of the card, in the format MMYY. | Required | String | 4 |
tokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , | Optional | String | 50 |
cardHolder | Cardholder name that appears on the card, for example, Mr John Smith. Allowed: alphanumeric, spaces, special characters ’ - | Optional | String | 256 |
Example:
PUT https://secure.paymarkclick.co.nz/api/token/card/6971410 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"cardToken": "6971410",
"cardExpiry": "0519",
"cardHolder": "Mr Jonathan Smith",
"tokenReference": "NewTokenReference"
}
Output Fields
Name | Description | Type |
---|---|---|
cardDetails | Details of the card. See table below for UDT structure. | UDT |
Name | Description | Type | Length |
---|---|---|---|
cardToken | Token identifier for the card. | String | 100 |
tokenReference | Merchant defined reference associated with the stored card token. | String | 100 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
cardHolder | The Cardholder name initially collected from the secure payment page. | String | 100 |
cardExpiry | Expiry date of the card, in format MMYY. | String | 100 |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service or method is not available. |
Card Token Not Found | The card token passed is not found or is invalid. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Remove a Card Token
This method removes the details of a previously stored card, by using the token value. The card details will be removed completely, with no way of reinstating them. This method is only available for tokens created using the “store card” method. Payment tokens cannot be used with this method.
Input Fields
The token identifier is passed in as part of the URL.
Example:
DELETE https://secure.paymarkclick.co.nz/api/token/card/6971410 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
Name | Description | Type |
---|---|---|
Success | Card token found and removed successfully. | Status code 204 with empty message. |
Failure | Card token not found. | Card Token Exception. |
Possible Exceptions
Exception | Description |
---|---|
Authorization Exception | Username and password are not correct or the web service or method is not available. |
Card Token Not Found | The card token passed is not found or is invalid. |
For a full list of REST exceptions, refer to the REST Exceptions section.
Shopify Plugin ¶
Overview
Click supports integration with Shopify. This section describes how to configure this plugin.
Set Up Integration
Before you start: You need to have an active Shopify store to be able to access the integration plugin.
-
Access the Click Shopify plugin.
-
The link will lead you to the login page. Login to your existing Shopify store.

- After logging in you will see the page prompting you to install Click. Select the button “Install payment provider”.

- You will be directed to the “Payments” settings page. Select the “Edit” button in the “Paymark Click” section.

- The section will expand. Enter the following fields:
Use test mode Check this option to integrate to a Click test (demo) account. By using a Click demo account, you can test your integration without moving any real money. All transactions will be passed through the Click payment simulator. Uncheck this to integrate to a Click production account.
ClientID:AccountID You can find the Client ID and Account ID in your Merchant activation email. Note: If you are using test mode, use the “Test Merchant Activation” email. If you are integrating to Production, use the “Production Merchant Activation” email. Be careful to enter information into the ClientID:AccountID field in the correct format, for example, 123456:987654.
Secret Hash Key You can find the Secret Hash Key in the Click Merchant Portal. Go to “Web Payments”, and then “Integration Settings”. You will see the Secret Hash Key listed under the “Secret Hash Key” section. Log in to the portal using the Username and Password credentials shown in the upper section of the activation email. To access the Merchant Portal, go to https://client.paymarkclick.co.nz/ (or for a test account, https://clientuat.paymarkclick.co.nz/). Notes: This is not the API Password (shown separately in the Merchant Portal). If you are using test mode, use the “Test Merchant Activation” email. If you are integrating to Production, use the “Production Merchant Activation” email.
Payment methods It is important to only select those you have loaded with Worldline. If you attempt a transaction with another payment method your Customer will see an error. To check what is loaded you can contact Worldline on 0800 PAYMARK.
Shopify payments settings page:
Activation email:
Merchant Portal:
-
After entering all Click settings, select the “Save” button.
-
You will now see the checkout process with Click as a payment option. After completing the order, your customers can pay using the Click hosted payment page.


Magento Plugin ¶
Overview
Paymark offers a free Magento plugin allowing you to take payments from a Magento 2.3 or 2.4 store via a Click Hosted Payment Page. You can see a demo website using the Click Magento plugin at https://paymark.onfiredigital.co.nz/.
Set Up Click account
We recommend setting your site up with a Click demo account, so that you can test the integration before going live and processing real payments.
Install Magento plugin
You can install the Click Magento plugin via Composer, using the following command:
composer require paymark/click
Alternatively download the package from GitHub and put the files into this folder in your Magento directory: app/Paymark/PaymarkClick
Once the plugin has been installed, run these two commands to enable the plugin:
#enable the plugin
php bin/magento module:enable Paymark_PaymarkClick
#run magento setup
php bin/magento setup:upgrade
Configure Magento plugin
After the module has been installed go to Stores > Settings > Configuration > Sales > Payment Methods in the Magento Admin to find the configuration options.
The configuration options are as follows:
-
Title: Title that will appear on the checkout page
-
Click User ID: User ID for your click account (You can find this in your merchant console after registering)
-
Click Password: Password for your click account (You can set this in your merchant console after registering)
-
Click Account ID: Click account id (You can find this in your merchant console after registering)
-
UAT: Flag to alternate UAT environment - this changes the payment URL
-
Debug Log: Write logs to paymark.log during the checkout process for debugging purposes
-
Payment Action: Option to either do an Authorisation charge or a full Capture (Paymark will need to enable the Authorisation option if you want to use this instead)
Go live
When you are ready to go live, you can register for a production Click account from your demo merchant console. Once your production account is set up, change the Click user ID, Click Password and Click Account ID to your production values and update the UAT flag in Magento so that your site is connected to your Click production account.
You’re now ready to accept payments online.
Reporting Service ¶
Overview
https://secure.paymarkclick.co.nz/api/report/transaction
By using the reporting service, Merchants can query and obtain a list of transactions that meet the input criteria.
The Reporting Service API is a RESTful API over HTTP, with a JSON payload.
Method Options
Requests should be sent as a GET web requests. Input data should be provided as part of the URL request. Once the request is received the input will be validated and, if successful, response will be returned in JSON format with body containing information for the requested transactions.
Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request.
If an error occurs, or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).
Input
Name | Description | Required | Type | Length |
---|---|---|---|---|
startDate | Starting date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. | Required | Datetime | N/A |
endDate | Ending date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. | Required | Datetime | N/A |
accountId | Account ID under which transaction should be searched for. If empty, method will search for all transactions under the merchant. | Optional | Integer | N/A |
reference | Reference value which transaction reference match partially to be included in the result. | Optional | String | 50 |
particular | Particular value which transaction particular match partially to be included in the result. | Optional | String | 50 |
type | Type of transactions to be included in the search result. Valid input values including: Purchase, Authorisation, OE_Payment, OE_Refund, Capture, Refund, Tokenise. If passing in empty or null, it will be treated as ALL. | Optional | String | 50 |
status | Status of the transactions to be included in the search result. Valid input values including: All, Successful, Declined, Failed, Blocked. If passing in empty or null, it will be treated as ALL. | Optional | String | 50 |
first6Digits | First 6 digits of the credit card used to make transactions that should be included in the result. | Optional | Integer | 6 |
last4Digits | Last 4 digits of the credit card used to make transactions that should be included in the result. | Optional | Integer | 4 |
cardExpiry | Expiry date of the card used to make transactions that should be included in the result, in the format MMYY. | Optional | Integer | 4 |
pageSize | Number of transactions to be returned. If no number is passed in, it is defaulted to 100. Maximum pageSize allowed is 15,000. | Optional | Integer | 50 |
Example:
GET https://secure.paymarkclick.co.nz/api/report/transaction?
startDate=2017-08-10T14:00:00&
endDate=2017-08-11T14:00:00&
accountId=700226&
reference=test&
particular=click&
type=purchase&
status=successful&
first6Digits=400555&
pageSize=5
HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Output Fields
Result will return a list of transactions including the following elements:
Name | Description | Type | Length |
---|---|---|---|
transactionId | Paymark Click defined unique transaction ID. | String | 8 |
originalTransactionId | Used in refund, capture and cancellation transactions. Contains the transaction ID for the related (authorisation or payment) transaction. | String | 8 |
type | Transaction type (PURCHASE, AUTHORISATION, REFUND, CAPTURE, OE_PAYMENT). | String | 50 |
accountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
batchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
receiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
authCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
capturedAmount | Captured amount of transaction in NZD, in the format 1.23. For Purchase, Refund and Online EFTPOS successful transactions, this field is the same as the Amount. For Authorisation transactions, this amount is the sum of all successful subsequent Capture transactions. For Capture transactions, this amount is set to 0. | Decimal | 20 |
refundedAmount | Refunded amount of transaction in NZD, in the format 1.23. For Purchase, Capture and Online EFTPOS successful transactions, this amount is the sum of all successful Refund transactions of the original transactions. For other types of transactions, this amount is set to 0. | Decimal | 20 |
surcharge | If the Merchant has added a surcharge % to this transaction, this is the surcharge amount for this transaction. Note: Contact Paymark to configure a surcharge for your Merchant account. | Decimal | 20 |
reference | Reference used for the transaction, as defined by the Merchant. | String | 50 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 50 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, DINERS_CLUB, QCARD). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
cardHolder | The Cardholder name entered into the Paymark Click hosted web payment page. | String | 100 |
cardStored | Whether or not the card was stored, false = not stored, true = stored. Will always be false for Online EFTPOS payments. | Boolean | 10 |
cardToken | Payment token for the card used for this transaction if chose to store the card, or if the transaction is a Tokenisation transaction. | String | 100 |
tokenReference | Merchant defined card token reference associated with the stored card used for this transaction. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
acquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 510 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. Only available if the merchantToken variable was set to 1. | String | 100 |
payerId | Consumer’s personal identifier for Online EFTPOS payments. | String | 100 |
payerIdType | Type of payerId that was used for Online EFTPOS payments. | String | 100 |
bank | Consumer bank to which the Online EFTPOS payment request was sent. | String | 100 |
Result Options
Result | Description |
---|---|
Success | 200 with body containing all transactions match input criteria. For each returned transaction, details are documented in the above “Output Elements” section, ordered by transaction date in descending order. Note: pageSize will determine how many transactions are returned. For example, if pageSise = 600, result will return up to 600 transactions. The maximum number of transactions returned is up to 15,000 |
Failure | See exceptions and errors below. |
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
400 Bad Request | 7004 | Start date cannot be greater than End date, please consult the payment web service integration manual. |
400 Bad Request | 7005 | Date range greater than 1 year, please restrict the date range, please consult the payment web service integration manual. |
400 Bad Request | 7006 | Transaction type not valid, please consult the payment web service integration manual. |
400 Bad Request | 7007 | Status not valid, please consult the payment web service integration manual. |
400 Bad Request | 7002 | Reference cannot contain more than 50 characters, please consult the payment web service integration manual. |
400 Bad Request | 5019 | Particular cannot contain more than 50 characters, please consult the payment web service integration manual. |
400 Bad Request | 8000 | pageSize must be between 1 and 15,000. |
400 Bad Request | 8000 | startDate is required. |
400 Bad Request | 8000 | endDate is required. |
400 Bad Request | 8000 | first6Digits must be 6 digits. |
400 Bad Request | 8000 | last4Digits must be 4 digits. |
400 Bad Request | 8000 | cardExpiry must be a valid MMYY format. |
400 Bad Request | 6023 | Client Account ID provided is not valid. |
400 Unauthorised | 3000 | Authentication error. Username and/or Password are incorrect. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
Marketing Token ¶
Overview
A marketing token can be created for the purpose of tracking all transactions made with a particular card, for example, for loyalty purposes. Transactions done through an EFTPOS terminal or online through Paymark Click can be tracked, providing an omnichannel facility for Merchants. Marketing tokens are supported for Click transactions through the Paymark Hosted Standard Payment, Direct Post and Merchant Hosted Transaction Processing integration options. Note: Currently you cannot create a marketing token for Online EFTPOS transactions.
A marketing token differs to a payment token or card token, which are created for the purpose of processing financial transactions. Unlike payment or card tokens, marketing tokens are not limited to standard card types (Visa, MasterCard, American Express and Q Card cards). A marketing token can also be created for an EFTPOS card to track all transactions made with that card via EFTPOS terminals.
Paymark Click is used to register and manage marketing tokens using the “Merchant Token” services.
End Points
For Standard Payment and Direct Post Click integrations, registration of a marketing token shares the same endpoints as Web Payments and is accessible at the below URLs:
Production: https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
Non-Production: https://uat.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest
For Merchant Hosted Transaction Processing, registration of a marketing token uses the following end points:
Production: https://secure.paymarkclick.co.nz/api/token/merchanttoken/
Non-Production: https://uat.paymarkclick.co.nz/api/token/merchanttoken/
Retrieval and removal of a marketing token (for all integration options) uses the following end points:
Production: https://secure.paymarkclick.co.nz/api/token/merchanttoken/
Non-Production: https://uat.paymarkclick.co.nz/api/token/merchanttoken/
Signing Up For The Marketing Token Service
This service is not offered as a standard Paymark Click feature. To sign up to use this facility, please contact Paymark on click@paymark.co.nz.
How Marketing Tokens Work
Standard Payment: When your web application registers a marketing token request, the Merchant Token service will return a unique URL that the Merchant application can use to load a secure Paymark Click page to register the marketing token. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Standard Payment service also offers the option to register a marketing token while processing a payment transaction. The “merchant_token” field in the Standard Payment request registers a marketing token and returns a marketing token identifier in the response.
Direct Post: When your web application registers a marketing token request, the Merchant Token service will return a Direct Post URL to which the marketing token details can be posted. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Direct Post service also offers the option to register a marketing token while processing a payment transaction. The “merchant_token” field in the Direct Post request registers a marketing token and returns a marketing token identifier in the response.
Merchant Hosted Transaction Processing: With this option, Merchants are able to utilise their own functions and processes to collect and store card details, and then make a direct server to server API call to register the marketing token via the Paymark Transaction Processing API. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Merchant Hosted Transaction Processing service also offers the option to register a marketing token while processing a payment transaction. The “merchantToken” field in the Merchant Hosted Transaction Processing request registers a marketing token and returns a marketing token identifier in the response.
Standard Payment Marketing Token Registration
Transaction Flow
For all cards, a marketing token can be registered using the Standard Payment request integration with the following flow.

When registering a marketing token using the Standard Payment request integration, the Click Web Payments API supports only the Post to Return URL return option. The return option determines what happens after a transaction is completed. See also Two Return Options.
The marketing token will be posted back to the Merchant’s return URL. At the same time, the Cardholder will be redirected back to the return URL. Note: Your return_url must have a valid SSL certificate to avoid the Cardholder’s browser prompting any security warning messages.
For information on registering a marketing token at the same time as the payment is done, see Paymark Hosted Standard Payment.
Marketing Token Registration Request Data
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
cmd | Defines the Web Payments integration service to use; for Standard Payment marketing token registration requests use “_xmerchanttoken”. | Required | String | N/A |
client_id | Your Paymark Click Client ID. | Required | Integer | N/A |
account_id | Your Paymark Click Account ID. | Required | Integer | N/A |
reference | Merchant defined reference associated with the marketing token. Allowed: alphanumeric, spaces, special characters _ - ’ ! @ # $ & * ( ) \ { } : " , . / | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
return_url | The URL that the Cardholder will be sent to on completion of the token creation. This must be a publicly accessible URL. | Required | String | 1024 |
notification_url | Additional URL where the transaction response will be sent to. This must be a publicly accessible URL. | Optional | String | 1024 |
Example:
POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=90127&
account_id=700152&
username=90127&
password=Paymark123&
reference=Reference&
particular=Particular&
cmd=_xmerchanttoken&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference
Note: Data is passed to the service as a URI query string so if a parameter contains URL punctuation characters it must be URL encoded. For example, reference=Ref?001 and particular=Part&001.
Marketing Token Request Result
Result Options
Result | Description |
---|---|
Success | See examples below. |
Failure | Returns REST error information in XML format. For a full list of REST exceptions, refer to the REST Exceptions section. |
Success Result Parameters
Name | Description | Data Type |
---|---|---|
cmd | Web Payments integration service. | String |
request | Encrypted request data. | String |
The marketing token registration URL returned will be wrapped in an XML element in string format. You will need to extract the URL out and XML decode the URL before you pass it to your “browser object”.
Example:
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=d8abe23b8c1143859d0baac26f825b0
</string>
Output Fields
The following table shows the output fields to be posted back to the Return URL, along with a brief description of each.
Name | Description | Type | Length |
---|---|---|---|
transactionDate | Date and time when the transaction was processed. | Datetime | N/A |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD, EFTPOS). | String | 50 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
merchantToken | The marketing token registered with Paymark for the card used for this transaction. | String | 100 |
reference | Merchant defined reference associated with the marketing token. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
errorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
errorMessage | The message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
Direct Post Marketing Token Registration
Transaction Flow
For all cards, a marketing token can be registered using the Direct Post integration with the following flow.

For information on registering a marketing token at the same time as the payment is done, see Direct Post.
Marketing Token Registration Request Data
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
cmd | Defines the Web Payments integration service to use; for Direct Post marketing token registration requests, use “_xdirectmerchanttoken”. | Required | String | N/A |
client_id | Your Paymark Click Client ID. | Required | Integer | N/A |
account_id | Your Paymark Click Account ID. | Required | Integer | N/A |
reference | Merchant defined reference associated with the marketing token. Allowed: alphanumeric, spaces, special characters _ - ’ ! @ # $ & * ( ) \ { } : " , . / | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ | Optional | String | 50 |
return_url | The URL that the Cardholder will be sent to on completion of the token creation. This must be a publicly accessible URL. | Required | String | 1024 |
notification_url | Additional URL where the transaction response will be sent to. This must be a publicly accessible URL. | Optional | String | 1024 |
Example:
POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=90127&
account_id=700152&
username=90127&
password=Paymark123&
reference=Reference&
particular=Particular&
cmd=_xdirectmerchanttoken&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference
Note: Data is passed to the service as a URI query string so if a parameter contains URL punctuation characters it must be URL encoded. For example, reference=Ref?001 and particular=Part&001.
Marketing Token Request Result
Result Options
Result | Description |
---|---|
Success | See examples below. |
Failure | Returns REST error information in XML format. For a full list of REST exceptions, refer to the REST Exceptions section. |
Success Result Parameters
Name | Description | Data Type |
---|---|---|
cmd | Web Payments integration service. | String |
request | Encrypted request data. | String |
The marketing token registration URL returned will be wrapped in an XML element in string format. You will need to extract the URL out and XML decode the URL before you pass it to your “browser object”.
Example:
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=6ac2b7f7c73c4f2fbb802f3751c630e2
</string>
Post Card Details Request
After the marketing token registration URL has been obtained from the step above, the Merchant web site can collect card information and post it to the URL.
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
card_expiry_month | Expiry month of the card, in the format MM. Required for standard card types. Ignored for EFTPOS cards. | Required | String | 2 |
card_expiry_year | Expiry year of the card, in the format YY. Required for standard card types. Ignored for EFTPOS cards. | Required | String | 2 |
card_number | Card number collected from Merchant’s token registration page. | Required | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=6ac2b7f7c73c4f2fbb802f3751c630e2 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
card_number=4987654321098769&
card_expiry_month=05&
card_expiry_year=17
Output Fields
While the marketing token registration is being processed, the Cardholder is redirected back to the Return URL that was in the marketing token registration request, along with the Result_Id.
Name | Description | Type |
---|---|---|
Result_Id | Identifier used to retrieve details for successful marketing token registration, or exception details for registrations with a REST Exception. | GUID |
Validating Result By Result ID
After Result_ID is returned from the previous step, the Merchant application can use the end point below to retrieve the transaction result.
The following table shows the input fields that can be posted to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
username | Your Paymark Click Client ID. | Required | String | 50 |
password | Your Paymark Click API Password. | Required | String | 50 |
account_id | Your Paymark Click Account ID. | Required | String | 50 |
result_id | Result ID returned from previous step after card details were posted. | Required | GUID | N/A |
Example:
GET https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/QueryDirectMerchantTokenResultByResultId HTTP/1.1
username=90127&
password=Paymark123&
account_id=700152&
result_id=e619459a-3c03-478f-b0c1-44a680ef87cc
Result Options
Result | Description |
---|---|
Success | XML containing standard outputs for requested transaction information. |
Failure | Returns REST error information in XML format. For a full list of REST exceptions, refer to the REST Exceptions section. |
Success Result Parameters
Element | Description | Type | Length |
---|---|---|---|
Status | Four possible status: PROCESSED, REJECTED, SESSION_EXPIRED, UNKNOWN. | String | 50 |
Message | Messages corresponding to status above: PROCESSED – “Transaction was processed”, REJECTED – “Transaction details failed validation”, SESSION_EXPIRED – “Session has expired”, UNKNOWN – “Unknown server error”. | String | N/A |
transactionResult | Details of the transaction. See table below for UDT structure. | UDT | N/A |
Name | Description | Type | Length |
---|---|---|---|
CardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
MerchantToken | The marketing token representing this card. | String | 100 |
Reference | Merchant defined reference associated with the marketing token. | String | 100 |
Particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
ErrorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
ErrorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
Merchant Hosted Transaction Processing Marketing Token Registration
For all cards, a marketing token can be registered using the Merchant Hosted Transaction Processing integration.
For information on registering a marketing token at the same time as the payment is done, see Merchant Hosted Transaction Processing.
Marketing Token Registration Request Data
The following table shows the input fields that can be posted to the Merchant Token API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Your Paymark Click Client ID. | Required | Integer | 8 |
cardExpiry | Card expiry date, in the format MMYY. E.g. 0520 for May 2020. Numeric format. Expiry dates in the past are allowed as long as the format is correct. Required for standard card types. Ignored for EFTPOS cards. | Required | String | 4 |
cardNumber | Card number without spaces. Numeric format. | Required | String | 12-19 |
reference | Merchant defined reference associated with the marketing token. Allowed: alphanumeric, spaces, special characters _ - ’ ! @ # $ & * ( ) + \ { } : " , . / | Optional | String | 50 |
particular | Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , + ? [ ] ( ) - _ | Optional | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/token/merchanttoken/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
{
"accountId":"700152",
"cardExpiry":"0520",
"cardNumber":"4987654321098769",
"reference":"Reference",
"particular":"Particular",
}
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
400 Bad Request | 2003 | Invalid account ID. |
400 Bad Request | 1004 | Card expiry must be in the correct format: MMYY. |
400 Bad Request | 1002 | Card number must be a valid credit card number. |
400 Bad Request | 50001 | Reference must be no more than 50 characters in length. |
401 Unauthorised | 3000 | Authentication error. Username, Account ID and/or password are incorrect. |
401 Unauthorised | 3001 | Authentication error. Service restricted or unavailable. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
Output Fields
The following table shows the output fields along with a brief description of each.
Name | Description | Type | Length |
---|---|---|---|
merchantToken | The marketing token registered with Paymark for the card used for this transaction. | String | 100 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardType | The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD, EFTPOS). | String | 50 |
reference | Merchant defined reference associated with the marketing token. | String | 100 |
particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
cardExpire | Card expiry date, in the format MMYY. E.g. 0520 for May 2020. Numeric format. | String | 4 |
createdDate | Date and time when marketing token was created. | Datetime | N/A |
Retrieve Marketing Token Using Merchant Reference
This method provides the functionality to retrieve the details of the marketing token using the Merchant’s reference provided when the token was registered.
Input Fields
The following table shows the input fields that can be posted to the Merchant Token API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type |
---|---|---|---|
reference | Reference for the marketing token to be found. | Required | String |
startDate | Starting date and time of registration transaction date to be included in the search result, inclusive. | Optional | Datetime |
endDate | Ending date and time of registration transaction date to be included in the search result, inclusive. | Optional | Datetime |
Example:
GET https://secure.paymarkclick.co.nz/api/token/merchanttoken/?
reference=Reference&
startDate=2017-08-01T00:00:00&
endDate=2017-08-02T00:00:00&
HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Output Fields
The following table shows the output fields along with a brief description of each.
Name | Description | Type | Length |
---|---|---|---|
merchantToken | The marketing token registered with Paymark for the card used for this transaction. | String | 100 |
cardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
cardType | The card type used for this token (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD, EFTPOS). | String | 50 |
reference | Merchant defined reference associated with the marketing token. | String | 100 |
particular | Particulars used for the registration transaction, as defined by the Merchant. | String | 100 |
cardExpire | Card expiry date, in the format MMYY. E.g. 0520 for May 2020. Numeric format. Expiry dates in the past are allowed as long as the format is correct. | String | 4 |
createdDate | Date and time when marketing token was created. | Datetime | N/A |
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
401 Unauthorised | 3000 | Authentication error. Username, Account ID and/or password are incorrect. |
401 Unauthorised | 3001 | Authentication error. Service restricted or unavailable. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
Remove a Marketing Token
This method provides the functionality to remove a previously registered marketing token.
Input Fields
The marketing token identifier is passed in as part of the URL.
The following table shows the other input fields required to remove a marketing token. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Your Paymark Click Account ID. | Required | Integer | N/A |
Example:
DELETE https://secure.paymarkclick.co.nz/api/token/merchanttoken/f0a0b18e-4ec7-4706-a869-da646cb35541 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"accountId":700152
}
Result Options
Result | Description |
---|---|
Success | 204 with empty message. |
Failure | See exceptions and errors below. |
Possible Errors and Exceptions
HTTP Response Code | Error Number | Error Message |
---|---|---|
404 Bad Request | 2002 | Invalid token ID. |
400 Bad Request | 2003 | Invalid Account ID. |
401 Unauthorised | 3000 | Authentication error. Username, Account ID and/or password are incorrect. |
401 Unauthorised | 3001 | Authentication error. Service restricted or unavailable. |
500 Internal Server Error | -1 | Unspecified error, contact Paymark. |
IVR Payments ¶
Introduction
Paymark Click can take payments and store cards for later use via an Interactive Voice Response (IVR) that is integrated to your own IVR or telephony platform. The Click IVR is not yet available for Online EFTPOS payments.
The Click IVR is offered as a bespoke implementation. Should you wish to integrate with the Click IVR, please contact Paymark on click@paymark.co.nz to discuss options.
How the Click IVR Works
There are three stages to an IVR transaction:
- Transaction Registration: Merchant system registers a transaction request with Click IVR.
- Transaction Processing: Paymark Click IVR collects card information and processes the transaction.
- Status Retrieval: Merchant system retrieves transaction status.
These stages are shown in the diagram below.

End Points
The Paymark Click IVR end points are accessible via the URLs below:
Production: https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/[MethodName]
Non-Production: https://uat.paymarkclick.co.nz/api/ivrpayments/registrar/rest/[MethodName]
HTTP Headers
In addition to the headers that are required by the HTTP protocol, Paymark requires that you specify the Accept header. The Accept header is used to specify the content type that your client will accept.
The following header is required for all REST API calls to the Click IVR:
Accept: application/xml
IVR Transaction Registration
The Paymark Click IVR Transaction Register method allows a Merchant system to register a transaction request with the Paymark Click IVR, and obtain a unique Registration ID for further transaction processing or retrieval of a transaction status.
Method name: register
This method receives transaction registration data. Data should be sent as a POST web request. All data should be provided in the body of the request.
Once the request is received, the input will be validated. If successful, a Registration ID will be returned. This Registration ID is then used to process the transaction and to retrieve the transaction status. If an error occurs or if invalid data is submitted, a response is provided to the requester in the form of XML message that includes an error code and a description (where applicable).
Request Data
The following table shows the input fields that can be posted to the Paymark Click IVR. These must be posted in the order shown in the table (alphabetical order). A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
AccountId | Your Paymark Click Account ID. | Required | Integer | N/A |
AllowStoreCardOption | 0 or 1 to indicate whether a Customer will be able to store the card. 0 = default, the Click IVR will not prompt the Customer to store the card. 1 = the Click IVR will give the Customer the option to store their card. | Optional | Integer | N/A |
Amount | The transaction amount in NZD. Must be a positive value (more than zero). | Required | Decimal | N/A |
HasStoredCard | 0 or 1 to indicate whether Customer has the option to replace an existing stored card. 0 = default, Customer has no existing stored card. 1 = The Merchant has an existing stored card for this Customer and the Click IVR will prompt the Customer to replace their existing card with a new stored card. | Required | Integer | N/A |
NotificationUrl | The URL where the transaction response will be sent to. This must be a publicly accessible URL. | Optional | String | 2048 |
Particular | Merchant defined value stored with the transaction. | Required | String | 50 |
Password | Your Paymark Click API Password. | Required | String | 50 |
Reference | Merchant defined value stored with the transaction. | Required | String | 50 |
ReturnPhoneNumber | The phone number of the Merchant system, where Customer should be redirected back to, after completing the transaction in the Click IVR. Format: 09XXXXXXX. | Required | String | 50 |
TokenReference | Merchant defined reference associated with the stored card token. Allowed: alphanumeric, spaces. | Optional | String | 50 |
Type | Type of transaction requested, “purchase” or “authorisation”, if not using the account’s (account_id) default transaction type. If type is omitted, this is taken from the default settings for the account_id used in this transaction. Contact Paymark to confirm the default setting for this account_id. Purchase is used to make a payment. Authorisation validates card details and holds funds on the card. If you are only storing the card for future payments, without validating card details, you can use type = “tokenise”. In this transaction the Amount and AllowStoreCardOption fields are ignored. | Optional | String | N/A |
Username | Your Paymark Click Client ID. | Required | String | 50 |
Example:
POST https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/register HTTP/1.1
Accept: application/xml
<RegisterIvrPaymentRequest xmlns="https://secure.paymarkclick.co.nz/api/">
<AccountId>700152</AccountId>
<AllowStoreCardOption>1</AllowStoreCardOption>
<Amount>5.23</Amount>
<HasStoredCard>0</HasStoredCard>
<NotificationUrl>https://merchanthost/ivr/</NotificationUrl>
<Particular>Particular</Particular>
<Password>Paymark123</Password>
<Reference>Reference</Reference>
<ReturnPhoneNumber>091234567</ReturnPhoneNumber>
<TokenReference>MerchantTokenRef</TokenReference>
<Type>authorisation</Type>
<Username>90127</Username>
</RegisterIvrPaymentRequest>
Request Result
Result | Description |
---|---|
Success | Registration ID in XML format: see example below. |
Failure | Returns REST error information in XML format. See REST Exceptions. |
On success, the Registration ID will be returned as a string in XML format.
Example:
<RegisterIvrPaymentResponse xmlns="https://secure.paymarkclick.co.nz/api/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<RegistrationId>100016</RegistrationId>
</RegisterIvrPaymentResponse>
IVR Transaction Processing
Once a transaction request has successfully been registered, the Merchant system should then transfer the call to the Paymark Click IVR to collect and process card information.
Request Data
The following table shows the input fields that can be posted to the Paymark Click IVR. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
CID | Caller ID (CID) needs to be set to the RegistrationID provided during the registration process. Transmission of the Caller ID needs to follow the NZ Bellcore FSK standard. | Required | Integer | N/A |
Request Result
Result | Description |
---|---|
Success | Transaction status (see Status Retrieval) gets posted back to the NotificationURL supplied by the Merchant during the registration process. The Customer call is transferred back to the Merchant system by transferring the call to the ReturnPhoneNumber supplied during the registration process. The CallerID set as the RegistrationID provided in the response to the transaction registration request. |
Failure | Same as for Success. |
IVR Transaction Status Retrieval
Once a transaction has been processed, the Merchant system can retrieve the transaction status using the Registration ID. The method below should be used to retrieve the transaction status. Note: Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request. See also Authentication information in Overview section.
Method Name: getstatus
Request Data
The following table shows the input fields that can be posted to the Paymark Click IVR. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.
Name | Description | Required | Type | Length |
---|---|---|---|---|
accountId | Your Paymark Click Account ID. | Required | String | 50 |
registrationId | Registration ID returned from the initial transaction registration. | Required | Integer | N/A |
Example:
GET https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/getstatus?
accountId=700152&
registrationId=100016
HTTP/1.1
Accept: application/xml
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Request Result
Result | Description |
---|---|
Success | XML containing standard outputs for requested transaction information. |
Failure | Returns REST error information in XML format. See REST Exceptions. |
Output Fields
Name | Description | Type | Length |
---|---|---|---|
Status | Status of the transaction. 1 = REGISTERED, 2 = IN_PROGRESS, 3 = COMPLETED, 4 = EXCEEDED_MAX_RETRY_CARD_NUMBER, 5 = EXCEEDED_MAX_RETRY_EXPIRY, 6 = EXCEEDED_MAX_RETRY_CSC, 7 = INVALID_CALLER_ID, 8 = HANGED_UP, 9 = UNKNOWN. | String | N/A |
Status Code | Refer to Status. | String | N/A |
Transaction | Details of the transaction. See table below for UDT structure. | UDT | N/A |
Name | Description | Type | Length |
---|---|---|---|
TransactionId | Paymark Click assigned unique transaction ID. | String | 8 |
Type | Transaction type (PURCHASE, AUTHORISATION, TOKENISE, REFUND, CAPTURE, CANCELLATION). | String | 50 |
AccountId | The Paymark Click Account ID used for processing the transaction. | Integer | 8 |
Status | Status of the transaction. 0 = UNKNOWN, 1 = SUCCESSFUL, 2 = DECLINED, 3 = BLOCKED, 4 = FAILED, 5 = INPROGRESS, 6 = CANCELLED. | String | 50 |
TransactionDate | Date and time when the transaction was processed. | Datetime | N/A |
BatchNumber | Content of this data can vary based on type of transaction. Currently when this contains a value, it is a string representing the “estimated settlement date” of the transaction. | String | 100 |
ReceiptNumber | Paymark Click defined unique receipt ID. | Integer | 8 |
AuthCode | Authorisation code returned by the Bank for this transaction. | String | 100 |
Amount | Amount of transaction in NZD, in the format 1.23. | Decimal | 20 |
Reference | Reference used for the transaction, as defined by the Merchant. | String | 100 |
Particular | Particulars used for the transaction, as defined by the Merchant. | String | 100 |
CardType | The card type used for this transaction. (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). | String | 50 |
CardNumber | Masked card number showing first 6 and last 4 digits of the card. | String | 100 |
CardExpiry | Expiry date of the card, in the format MMYY. | String | 100 |
CardHolder | Defaults to “IVR System” for IVR transactions. | String | 100 |
CardStored | Whether or not the card was stored: 0 = not stored, 1 = stored. | Boolean | 10 |
CardToken | The token of the newly stored card, only available if the cardStored variable was set to 1 and the Cardholder chose to store their card details. | String | 100 |
ErrorCode | The error code indicating the type of error that occurred. See Response Codes and Messages for a full listing of error codes. | String | 4 |
ErrorMessage | The error message explaining what the error means. See Response Codes and Messages for a full listing of error codes. | String | 510 |
AcquirerResponseCode | Response code from the acquirer to indicate the status and errors of a particular transaction processed. | String | 6 |
TokenReference | Merchant defined reference associated with the stored card token. | String | 50 |
Voice Prompt Files
The voice prompt files used in the IVR announcements can be either a .wav or .gsm file. Maximum file size is 15 KB. Files need to be sent to your integration contact person.
Merchant Web Site Requirements ¶
When a Merchant processes payments from their own web site (Direct Post and Merchant Hosted Transaction Processing (“two party payment”)), the Merchant’s web site needs to comply with the following requirements.
In addition, for Merchants that support Online EFTPOS payments, these acceptance mark guidelines apply.
General Requirements
The Merchant’s web site needs to be secured using a SSL certificate.
There is no initial requirement for the Merchant to have a CAPTCHA type real person authentication method; Paymark reserves the right to ask the Merchant to implement such a feature.
From 30 April 2018, Paymark will cease support for TLS 1.0 and 1.1. You must connect with TLS 1.2.
Branding Requirements
A Paymark logo must always be displayed on the payment page. Please contact Paymark for logos and branding requirements.
Online EFTPOS Requirements
If Online EFTPOS is enabled, the Merchant’s web site needs to provide information on Online EFTPOS with this payment method, for example, mouse over help text. The copy for this is: “For help on installing and using your bank’s mobile app please visit their website.”.
The Online EFTPOS payerID must be validated for general correctness, for example, correct number of digits. Paymark will provide copy to display in the event the payerID has failed this validation.
Mobile number validation rules for all Consumer Banks are:
-
Begins with 020 / 1 / 2 / 7 / 8 / 9 (zero two …).
-
023, 024, 025, 026 not allowed.
-
Minimum 9 digits, maximum 11 digits.
-
Only numeric characters allowed.
Examples (not exhaustive!):
Allowed:
-
021012345
-
0221234567
Not allowed:
-
021-012-345
-
+64 22 123 4567
-
026123456
The Merchant may choose to add additional usability aids such as a drop down list of valid mobile prefixes.
In addition, for Co-operative Bank payments, Customer ID validation rules are:
-
Exactly 7 digits
-
Begins with 1 - 9
In addition, for Westpac payments, Westpac 1 ID validation rules are shown below.
There are two types of Westpac One IDs: both are sent to Click with the payerIdType “WESTPAC1ID”.
“Tele ID”: 4 - 9 digits long, can start with any number. “Self Selected ID”: 4 - 20 character string, minimum one letter, valid characters are letters: [A-Z a-z], numbers: [0-9], fullstop, underscore, dash, backslash: [ . _ - \ ].
Determining the Payer ID Type:
-
If all numbers and meets the mobile number validation, payerIdType = “MOBILE”. Note: This includes 9 digit numbers starting with “02”. Else,
-
If all numbers and NOT a mobile number (as above), must be a Tele ID, so validate as per Tele ID criteria above, and if valid, payerIdType = “WESTPAC1ID”.
-
If at least 1 letter, must be a Self Selected ID, so validate as per Self Selected ID criteria above, and if valid, payerIdType = “WESTPAC1ID”.
For specific requirements on the presentation and handling of Online EFTPOS payments, please refer to the Online EFTPOS API specification or contact Paymark with any questions on click@paymark.co.nz.
REST Exceptions ¶
Overview
This section details the API error codes and messages that may be seen in the Paymark Click APIs. In the event a REST Exception occurs, the transaction would be rejected by the API.
The table below contains the standard HTTP response codes and related service error number(s) for the REST methods.
HTTP Response Code | Error Number (see table below for related error messages) |
---|---|
400 Bad Request | Error numbers 5000 to 5100 |
401 Unauthorised | Error numbers 3000 and 3001 |
404 Not Found | Error number 2000 |
406 Not Acceptable | Error number 5406 |
415 Unsupported Media Type | Error number 5415 |
500 Internal Server Error | Error number -1 |
The “error type” element will contain one of the following denoting the type of exception:
-
AUTHENTICATION Occurred whilst authenticating the service consumer.
-
PARAMETER Occurred whilst validating a parameter passed to the service.
-
SERVICE Occurred while processing the request.
-
UNSPECIFIED Occurred unexpectedly, contact Paymark.
Example:
401 Unauthorised
REST APIs Error Messages
The REST APIs (including Merchant Hosted transaction processing) will return the error message in JSON format.
{
"code": 3000,
"message": "Authentication error. Username, AccountId and/or Password are incorrect"
}
Paymark Hosted Standard Payment and Direct Post Error Messages
The Paymark Hosted standard payment API (Paymark Click hosted payment page) and Direct Post API will return the error message in XML format.
Standard payment response message XML example:
<error
xmlns="https://secure.paymarkclick.co.nz/api/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<errormessage>Authentication error. Username, AccountId and/or Password are incorrect</errormessage>
<errornumber>3000</errornumber>
<errortype>AUTHENTICATION</errortype>
</error>
IVR Error Messages
The IVR API will return the error message in XML format.
IVR response message XML example:
<Error
xmlns="https://secure.paymarkclick.co.nz/api/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorMessage>Authentication error. Username, AccountId and/or Password are incorrect</ErrorMessage>
<ErrorNumber>3000</ErrorNumber>
<ErrorType>AUTHENTICATION</ErrorType>
</Error>
Payment Service Errors
Error Number | Error Message |
---|---|
-1 | Unspecified Error - Contact Paymark |
1000 | Card number must contain a value |
1001 | Card number must be all digits |
1002 | Card number must be a valid credit card number |
1003 | Card holder name must contain a value and be 256 characters or less in length |
1004 | Card expiry must be in the correct format: MMyy |
1005 | Card expiry must only contain digits and be in the format: MMyy |
1006 | Card expiry must be in the future |
1007 | Card type must contain one of the following values: MC, VISA, AMEX, QCARD |
1008 | Card type must be correct for the card number given |
1009 | Merchants may only transact with card types linked to their account |
1010 | Card CSC must be 3 or 4 digits in length |
1011 | A one dollar authorisation failed using the supplied card details |
1012 | The supplied Token Reference must be 50 characters or less |
1013 | You must supply a Token Reference |
1014 | An error occurred when adding the card. Please contact Paymark. |
2000 | Card token not found |
2001 | Card token is currently used/linked to other services, please use the merchant console to manage this token |
3000 | Authentication error. Username and/or Password are incorrect |
3001 | Authentication error. Service restricted or unavailable |
3002 | Authorization error. Service restricted or unavailable, please contact Paymark |
3003 | Authentication error. Merchant account is inactive |
3004 | Authentication error. This method is unavailable, possible causes are that the channel or service to which it belongs is not currently subscribed. |
4000 | Paymark Account ID is invalid |
4006 | Amount must be positive |
4007 | Total Amount must be greater than the sum of Amount and the cost of the transaction |
4010 | An error occured whilst processing the credit card transaction |
5000 | Payment Account ID is invalid |
5001 | Reference field is invalid, please consult the payment web service integration manual for allowed length and format |
5002 | Particular field is invalid, please consult the payment web service integration manual for allowed length and format |
5003 | Payment Amount must be positive |
5004 | Email Address must be a valid email |
5005 | Original transaction not found |
5006 | Original transaction invalid |
5015 | Transaction Frequency not valid |
5007 | An error occured whilst processing your transaction, please contact Paymark |
5008 | An error occured whilst processing your refund, please contact Paymark |
5009 | Total amount captured can not exceed the original authorisation amount |
5010 | Payment type must be 0 for purchase and 1 for authorisation |
5011 | Payment type selected is not valid for the Paymark Account ID passed |
5013 | This account is not enabled to make refunds. Please contact Paymark. |
5016 | The Online Eftpos Merchant not configured |
5017 | The Online Eftpos Payer Id is not valid |
5018 | The Online Eftpos transaction is not valid |
5019 | Transaction not found |
5020 | Total amount refunded can not exceed the available amount |
5021 | The Online Eftpos Payer Id Type is not valid |
5022 | Web payments: The Online Eftpos Bank is not valid. IVR: The field reference must be a string with a maximum length of 50. |
5023 | Web payments: The provided Conditional Indicator is not valid. IVR: The field particular must be a string with a maximum length of 50. |
5024 | Web payments: Transaction already cancelled. IVR: The field ReturnPhoneNumber must be a string with a maximum length of 50. |
5025 | Cancellation not permitted on this transaction |
5037 | The return_url field is required. |
5042 | The field store_card must be between 0 and 1. |
5043 | The field display_customer_email must be between 0 and 1. |
5044 | Payment method is not valid. |
5045 | Client ID is not valid. |
5046 | The token reference field must be a string with a maximum length of 50. |
5047 | The field store_card_without_input must be between 0 and 1. |
5048 | The field transaction_source must be MOTO or INTERNET. |
5049 | The field AllowStoreCardOption must be between 0 and 1. |
5050 | The field HasStoredCard must be between 0 and 1. |
5100 | Invalid or empty Web Payments URL. |
5406 | Not acceptable. |
5415 | Unsupported media type. |
6000 | Consumer email address is not a valid email |
6001 | Plan start date must be after today |
6003 | Plan frequency must be one of the accepted values, please consult the payment web service integration manual |
6002 | Plan start date must be the last business day for the frequency selected |
6004 | Consumer Title is invalid, please consult the payment web service integration manual for length and format rules |
6005 | Consumer First Name(s) is invalid, please consult the payment web service integration manual for length and format rules |
6006 | Consumer Last Name is invalid, please consult the payment web service integration manual for length and format rules |
6007 | Consumer Address1 is invalid, please consult the payment web service integration manual for length and format rules |
6008 | Consumer Address2 is invalid, please consult the payment web service integration manual for length and format rules |
6009 | Consumer Address3 is invalid, please consult the payment web service integration manual for length and format rules |
6010 | Consumer Suburb is invalid, please consult the payment web service integration manual for length and format rules |
6011 | Consumer City is invalid, please consult the payment web service integration manual for length and format rules |
6012 | Consumer Postcode is invalid, please consult the payment web service integration manual |
6013 | Consumer Home Telephone is invalid, please consult the payment web service integration manual for length and format rules |
6014 | Consumer Work Telephone is invalid, please consult the payment web service integration manual for length and format rules |
6015 | Consumer Mobile Telephone is invalid, please consult the payment web service integration manual for length and format rules |
6016 | Consumer Fax Number is invalid, please consult the payment web service integration manual for length and format rules |
6017 | Consumer Email too long, please consult the payment web service integration manual |
6018 | Termination date provided is incorrect for the frequency selected |
6019 | Number of Payments must be a positive integer |
6020 | Amount must be a positive value |
6021 | Reference field is invalid, please consult the payment web service integration manual for allowed length and format |
6022 | Particular field is invalid, please consult the payment web service integration manual for allowed length and format |
6023 | Client Account ID provided is not valid |
6024 | Client Account ID provided is incorrect |
6025 | Recurring Card Plan is not Active |
6026 | Recurring Card Plan is not in an Active or Suspended state |
6027 | Recurring Card Plan does not exist |
6028 | Recurring Card Plan is not Suspended |
6029 | Consumer date of birth is an invalid date |
6030 | Consumer country has an invalid id, please consult the payment web service integration manual |
7000 | Reference cannot be passed null or contain more than 50 characters, please consult the payment web service integration manual |
7001 | Particular cannot be passed null or contain more than 50 characters, please consult the payment web service integration manual |
7002 | Reference cannot contain more than 50 characters, please consult the payment web service integration manual |
7003 | Particular cannot contain more than 50 characters, please consult the payment web service integration manual |
7004 | Start date cannot be greater than End date, please consult the payment web service integration manual |
7005 | Date range greater than 1 year, please restrict the date range, please consult the payment web service integration manual |
7006 | Transaction type not valid, please consult the payment web service integration manual |
7007 | Status not valid, please consult the payment web service integration manual |
7008 | Page size not valid, please consult the payment web service integration manual |
8000 | Some of the data provided is invalid, please consult the payment web service integration manual for allowed format |
Transaction Response Codes and Messages ¶
Overview
This section details the transaction responses and messages, including bank error codes, that may be seen in the Paymark Click APIs.
Transaction Responses and Error Messages
Once a transaction is successfully submitted for processing, that is, no REST Exceptions have occurred, the transaction response returned will indicate the status of the transaction along with an error code and error message (if not successful).
Status | Response Code | API Error Message | Acquirer Response code(s) |
---|---|---|---|
Successful | 200 | Transaction Successful | 00 |
Declined | 200 | Insufficient Funds | 51, 61 |
Declined | 201 | Transaction Declined - Expired Card | 54 |
Declined | 202 | Bank Declined Transaction | 01, 04, 05, 08, 21, 31, 39, 43, 52, 53, 55, 60, 65, 75, 94, 98 |
Declined | 203 | Transaction Declined - Bank Error | 02, 03, 06, 10, 14, 18, 20, 23, 25, 29, 33, 34, 40, 41, 44, 59, 62, 64, 70, 76, 79, 82, 83, 84, 86, 87, 89, 90, 92, 93, 95, 97 |
Declined | 204 | Transaction Type Not Supported | 08, 57, 58 |
Declined | 205 | Card Security Code verification failed | |
Declined | 206 | Address Verification Failed | |
Declined | 207 | Address Verification and Card Security Code Failed | |
Declined | 208 | Declined - Issuing bank rejected 3DS authentication | |
Declined | 250 | Declined - Unauthorised | |
Declined | 251 | Declined - Account does not exist | |
Declined | 252 | Declined - Payment stopped | |
Declined | 253 | Declined - Authority cancelled | |
Declined | 254 | Declined - Account closed | |
Declined | 255 | Declined - Account transferred | |
Declined | 256 | Declined - Payment limit exceeded | |
Declined | 257 | Declined - Invalid Account | |
Declined | 270 | Declined - 3DSecure authentication failed | |
Declined | 271 | Declined - Card not enrolled in 3DSecure | |
Declined | 272 | Declined - Card enrolled but holder not registered with 3DSecure | |
Declined | 273 | Declined - Transaction Declined | |
Declined | 299 | Declined - Unknown dishonour | |
Failed | 300 | Failed - Error communicating with provider | |
Failed | 301 | Error communicating with the bank (check card details) | 91, 96 |
Failed | 302 | No Reply from Bank | |
Failed | 303 | Payment Server detected an error | 30 |
Failed | 304 | Shopping Transaction Locked (Please try the transaction again later) | |
Failed | 305 | Transaction was not processed - Reached limit of retry attempts allowed | |
Failed | 306 | Duplicate SessionID | |
Failed | 307 | Card Issuer Institution Returned a Referral Response | |
Failed | 353 | Unable to process 3DSecure transaction | |
Failed | 360 | Online EFTPOS Unsubmitted | |
Failed | 361 | Online EFTPOS Transaction Expired | |
Failed | 398 – 400 | Trusted payments not allowed for this merchant. This means either the Merchant is not enabled for Online EFTPOS Autopay, or the Consumer has revoked the Online EFTPOS Autopay arrangement. |
|
Failed | 398 – 409 | Invalid request. Trust already exists. This means the Merchant tried to set up Online EFTPOS Autopay arrangement for a bank / payerId / payerIdType combination that already exists for this Merchant. |
|
Failed | 398 | Internal Error | |
Failed | 399 | Transaction Failed | |
Blocked | 400 | Transaction Rule Violation: Minimum Transaction Amount | |
Blocked | 401 | Transaction Rule Violation: Maximum Transaction Amount | |
Blocked | 402 | Transaction Rule Violation: Daily Transaction Amount | |
Blocked | 403 | Transaction Rule Violation: Daily Transaction Volume | |
Blocked | 404 | Transaction Rule Violation: Monthly Transaction Amount | |
Blocked | 405 | Transaction Rule Violation: Monthly Transaction Volume | |
Blocked | 406 | Transaction Rule Violation: Card Amount Limit Reached | |
Blocked | 407 | Transaction Rule Violation: Card Successful Volume Limit Reached | |
Blocked | 408 | Transaction Rule Violation: Card Unsuccessful Volume Limit Reached | |
Blocked | 409 | Transaction Rule Violation: Overseas issued card. Issue Country: {0} | |
Blocked | 410 | Transaction Rule Violation: Card is on Blocked List | |
Blocked | 411 | Transaction Rule Violation: Detected a duplicate Transaction Reference | |
Blocked | 415 | Blocked - 3DS status unavailable | |
Blocked | 470 | Transaction Rule Violation: Refund Daily Transaction Amount | |
Blocked | 471 | Transaction Rule Violation: Total amount refunded can not exceed the original transaction amount | |
Blocked | 498 | Transaction Rule Violation: No Rules Set | |
Blocked | 499 | Transaction Rule Violation: Transaction blocked | |
Cancelled | 800 | Transaction Cancelled | |
Cancelled | 801 | Transaction Aborted | |
Unknown | 900 | Transaction Result Unknown. Unable to ascertain the transaction result. Please contact Paymark. | |
Unknown | 901 | Transaction may not have completed | |
Unknown | 902 | Unable to obtain transaction result, service temporarily unavailable. | |
Unknown | 903 | 3DSecure authentication may not have completed | |
Unknown | 999 | Blank |
Test Card Details ¶
Overview
This section details the test cards that may be used in the Click non-production environment.
Important: Please ensure you do not use real (production) card data within the non-production environment.
Card Numbers
To process test transactions within the non-production environment you must use one of the cards listed below.
Card Type | Card Number | Card Expiry (MM/YY) | CSC | Response Code | Transaction Status |
---|---|---|---|---|---|
MasterCard | 5123456789012346 | 12/24 | 111 | 00 | Successful |
MasterCard | 5290075430806729 | 12/24 | 111 | 01 | Bank Declined Transactions |
MasterCard | 5538737873773631 | 12/24 | 111 | 05 | Bank Declined Transactions |
MasterCard | 5265340072069809 | 12/24 | 111 | 12 | Transaction Type Not Supported |
MasterCard | 5307995509923512 | 12/24 | 111 | 31 | Bank Declined Transactions |
MasterCard | 5114996316783803 | 12/24 | 111 | 51 | Insufficient Funds |
MasterCard | 5178468787602840 | 12/24 | 111 | 54 | Expired Card |
MasterCard | 5510545567805243 | 12/24 | 111 | 91 | Error Communicating with Bank (Check Card Details) |
MasterCard | 2221006789012347 | 12/24 | 111 | 00 | Successful |
MasterCard | 2221005430806727 | 12/24 | 111 | 01 | Declined |
MasterCard | 2221007873773638 | 12/24 | 111 | 05 | Declined |
MasterCard | 2221000072069809 | 12/24 | 111 | 12 | Declined |
MasterCard | 2221005509923510 | 12/24 | 111 | 31 | Declined |
MasterCard | 2221006316783808 | 12/24 | 111 | 51 | Declined |
MasterCard | 2221008787602848 | 12/24 | 111 | 54 | Declined |
MasterCard | 2221005567805245 | 12/24 | 111 | 91 | Declined |
MasterCard | 5391715789309969 | 12/24 | 111 | 10 | Partial authorisation (half the requested amount is approved for an authorisation transaction) |
MasterCard 3D Secure | 5422882800700007 | 12/24 | 111 | 00 | Successful |
MasterCard 3D Secure | 2239468872817471 | 12/24 | 111 | 00 | Successful |
MasterCard 3D Secure | 2239464831923120 | 12/24 | 123 | 10 | Partial authorisation (half the requested amount is approved for an authorisation transaction) |
MasterCard 3D Secure | 5257221203980330 | 12/24 | 123 | 00 | Successful (blank AAV) |
MasterCard 3D Secure | 5573216845946050 | 12/24 | 123 | 00 | Successful (blank AAV) |
MasterCard 3D Secure | 5583731329831220 | 12/24 | 123 | 00 | Attempted Authentication (blank AAV) |
VISA | 4987654321098769 | 12/24 | 111 | 00 | Successful |
VISA | 4929474753922860 | 12/24 | 111 | 01 | Bank Declined Transactions |
VISA | 4539032811676621 | 12/24 | 111 | 05 | Bank Declined Transactions |
VISA | 4886709226179775 | 12/24 | 111 | 12 | Transaction Type Not Supported |
VISA | 4556989846299273 | 12/24 | 111 | 31 | Bank Declined Transactions |
VISA | 4556989785924709 | 12/24 | 111 | 51 | Insufficient Funds |
VISA | 4916146026583852 | 12/24 | 111 | 54 | Expired Card |
VISA | 4929233907988775 | 12/24 | 111 | 91 | Error Communicating with Bank (Check Card Details) |
VISA | 4556286124462032 | 12/24 | 111 | 10 | Partial authorisation (half the requested amount is approved for an authorisation transaction) |
VISA 3D Secure | 4918914107195005 | 12/24 | 111 | 00 | Successful |
VISA 3D Secure | 4988721001931418 | 12/24 | 111 | 00 | Card Not Enrolled |
American Express | 345678901234564 | 12/24 | 1111 | 00 | Successful |
American Express | 372230337931151 | 12/24 | 1111 | 01 | Bank Declined Transactions |
American Express | 374991708241573 | 12/24 | 1111 | 05 | Bank Declined Transactions |
American Express | 371142424142835 | 12/24 | 1111 | 12 | Transaction Type Not Supported |
American Express | 379864718969977 | 12/24 | 1111 | 31 | Bank Declined Transactions |
American Express | 377799096385150 | 12/24 | 1111 | 51 | Insufficient Funds |
American Express | 379269138331578 | 12/24 | 1111 | 54 | Expired Card |
American Express | 375811155501015 | 12/24 | 1111 | 91 | Error Communicating with Bank (Check Card Details) |
Online EFTPOS Sandbox ¶
Overview
The Online EFTPOS Sandbox is part of the Paymark Click non-production environment.
The sandbox can be used to simulate Online EFTPOS payment and refund operations for each Consumer Bank (ASB, The Co-operative Bank, Heartland and Westpac). The transaction amount used in the payment or refund request will determine the response that is received.
ASB Transactions
The following responses can be simulated for ASB transactions (bankId = ASB).
Payment Request
Status updates for “consumer responses” are received approximately 10 seconds after the payment request has been sent; the status in the response to the initial request is SUBMITTED.
The terminal status will be received in the response to the initial request for all “system responses”.
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount under $1 (100c) or over $1.20 (120c) | Consumer has authorised the payment. | Consumer response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
117c | Payment has been declined by the Consumer. | Consumer response |
101c | Consumer does not have Bank mobile app registered for this payerId (mobile number for ASB). | System response |
102c | Consumer does not have Bank mobile app registered (app not set up for use). | System response |
103c | Consumer has Online EFTPOS disabled (PayHere turned off for ASB). | System response |
104c | Consumer has no default bank account. | System response |
105c | Consumer is over their account limit. | System response |
Expired Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
118c | Consumer did not action the payment request within four minutes (expiry timeout has been passed). | (Lack of) Consumer response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
111c | Duplicate payment request. | System response |
112c | Paymark system issue (refer to Paymark). | System response |
113c | Paymark system issue (Online EFTPOS disabled for this Bank). | System response |
115c | Payment request formatted incorrectly. | System response |
116c | Paymark system issue (authentication). | System response |
Refund Request
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount under $1 (100c) or over $1.20 (120c) | Refund has been successfully processed. | Bank response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
101c | Consumer does not have Bank mobile app registered for this payerId (mobile number for ASB). | System response |
102c | Consumer not registered for Online EFTPOS (formerly known to ASB customers as Pay Here). | System response |
103c | Consumer is not active at this Bank. | System response |
104c | Consumer has no default bank account. | System response |
105c | Consumer is over their account limit. | System response |
110c | Refund exceeds available funds (this refund would put the Merchant in a negative settlement position, which is not allowed for Online EFTPOS). | System response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
108c | Bank system issue. | System response |
111c | Duplicate refund request. | System response |
112c | Paymark system issue (refer to Paymark). | System response |
113c | Paymark system issue (Online EFTPOS disabled for this Bank). | System response |
115c | Payment request formatted incorrectly. | System response |
116c | Paymark system issue (authentication). | System response |
Note: The expire scenario does not apply to refunds as these require no Consumer action.
The Co-operative Bank (Co-op) Transactions
The following responses can be simulated for Co-op transactions (bankId = COOPERATIVE).
Payment Request
Status updates for “consumer responses” are received approximately 10 seconds after the payment request has been sent; the status in the response to the initial request is SUBMITTED.
The terminal status will be received in the response to the initial request for all “system responses”.
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount over $1.20 (120c) | Consumer has authorised the payment. | Consumer response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
117c | Payment has been declined by the Consumer. | Consumer response |
102c | Bank has declined the transaction for some reason, for example, the Consumer’s account is closed. | System response |
Expired Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
118c | Consumer did not action the payment request within four minutes (expiry timeout has been passed). | (Lack of) Consumer response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
104c | An error occurred when the payment request was sent to the Bank. | System response |
Refund Request
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount over $1.20 (120c) | Refund has been successfully processed. | Bank response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
102c | Bank has declined the transaction for some reason. | System response |
110c | Refund exceeds available funds (this refund would put the Merchant in a negative settlement position, which is not allowed for Online EFTPOS). | System response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
104c | An error occurred when the refund request was sent to the Bank. | System response |
Note: The expire scenario does not apply to refunds as these require no Consumer action.
Heartland Bank Transactions
The following responses can be simulated for Heartland Bank transactions (bankId = HEARTLAND).
Payment Request
Status updates for “consumer responses” are received approximately 10 seconds after the payment request has been sent; the status in the response to the initial request is SUBMITTED.
The terminal status will be received in the response to the initial request for all “system responses”.
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
130c ($1.30) | Consumer has authorised the payment. | Consumer response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
131c | Payment has been declined by the Consumer. | Consumer response |
101c, 102c, 103c | Consumer has not opted in for Online EFTPOS payments. The Consumer should contact Heartland Bank to enable Online EFTPOS. | System response |
104c | No account maintained for Online EFTPOS. The Consumer should contact Heartland Bank for assistance. | System response |
105c | Total transaction amount exceeds daily limit. The Consumer should contact Heartland Bank for assistance. | System response |
Expired Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
132c | Consumer did not action the payment request within four minutes (expiry timeout has been passed). | (Lack of) Consumer response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
108c | System error. Contact Heartland Bank for assistance. | System response |
115c | Paymark system issue (refer to Paymark). | System response |
116c | Paymark system issue (refer to Paymark). | System response |
Refund Request
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Less than or equal to the approved payment amount. | Refund has been successfully processed. | Bank response |
Declined Scenarios
Declined scenarios are not available in the Online EFTPOS Sandbox for Heartland Bank transactions.
Expired Scenarios
The expired scenario does not apply to refunds as these require no Consumer action.
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
106c | No source reference number in the system. Invalid refund request. Contact Heartland Bank for assistance. | System response |
110c | Total of refund amounts exceeds the original payment amount. | System response |
Westpac Transactions
The following responses can be simulated for Westpac transactions (bankId = WESTPAC).
Payment Request
Status updates for “consumer responses” are received approximately 10 seconds after the payment request has been sent; the status in the response to the initial request is SUBMITTED.
The terminal status will be received in the response to the initial request for all “system responses”.
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount over $1.20 (120c) | Consumer has authorised the payment. | Consumer response |
Declined Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
105c | Consumer is over their account limit. | System response |
106c | Payer ID is not registered to a Westpac customer. | System response |
117c | Payment has been declined by the Consumer. | Consumer response |
118c | Consumer is not registered with Westpac. | System response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
101c | Invalid mobile number. | System response |
108c | General system error (attempt the payment again). | System response |
111c | Duplicate request (Consumer needs to action the original payment request). | System response |
112c | Invalid PSP ID (contact Paymark for assistance). | System response |
113c | PSP disabled (contact Paymark for assistance). | System response |
115c | Data error (contact Paymark for assistance). | System response |
116c | Invalid signature (contact Paymark for assistance). | System response |
Note: The expire scenario is not yet supported for Westpac Sandbox payments.
Refund Request
Authorised Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
Any amount over $1.20 (120c) | Refund has been successfully processed. | Bank response |
Error Scenarios
Transaction Amount | Response Description | Response Type |
---|---|---|
106c | Payment not found. | System response |
107c | Original payment was not completed. | System response |
108c | General system error (attempt the refund again). | System response |
110c | Refund exceeds available funds (this refund would put the Merchant in a negative settlement position, which is not allowed for Online EFTPOS). | System response |
111c | Duplicate request (Merchant needs to wait for the original refund to be processed). | System response |
112c | PSP not registered (contact Paymark for assistance). | System response |
113c | Paymark system issue (Online EFTPOS disabled for this Bank). | System response |
115c | Data error (contact Paymark for assistance). | System response |
116c | Invalid signature (contact Paymark for assistance). | System response |
Notes:
-
The declined scenario does not apply to Westpac Sandbox refunds.
-
The expire scenario does not apply to refunds as these require no Consumer action.
Online EFTPOS Autopay ¶
Overview
Online EFTPOS Autopay enables a Merchant to create a payment token for Online EFTPOS payments, then use this token to subsequently charge the Customer when they elect to pay using Online EFTPOS.
Online EFTPOS Autopay is available to eligible Merchants. Please contact Paymark on click@paymark.co.nz if you wish to discuss Online EFTPOS Autopay.
Before you set up Autopay there are a number of prerequisties you need to consider. You can see the details here.
Transaction Flow
The diagram below provides an overview of the Online EFTPOS Autopay transaction flows. When we discuss enabling Online EFTPOS Autopay with you, we will take you through this flow to ensure your Customers’ experience is optimised.

Account Holder Statement
For Online EFTPOS payments, the Merchant can control some information that appears on the Account Holder’s bank statement, specifically the Merchant short name, and the reference used for the payment.
The “Merchant short name” is a 12 character version of the Merchant’s name. This is set up when you add Online EFTPOS as a payment method. Contact Paymark on click@paymark.co.nz to confirm what your Merchant short name is.
The Account Holder also sees the reference that was included with the transaction request. If this reference is more than 12 characters, this will be truncated on the Account Holder’s statement.
Click Feature Releases ¶
Overview
This section details the most recent releases for the Click APIs and Merchant Portal.
APIs
Westpac now available for Online EFTPOS payments on the Paymark Click hosted payment page
For Merchants integrating with the Paymark Hosted Standard Payment model, Online EFTPOS is now offered for four banks: ASB, The Co-operative Bank, Heartland and Westpac. No changes are needed to your integration for your Customers to pay using their Westpac bank account.
For Merchants integrating to Click with Direct Post or Merchant Hosted Transaction Processing, this API spec details how Westpac will be supported in the future. If you are intending to offer Westpac for Online EFTPOS payments, please contact us on click@paymark.co.nz to discuss options.
Status Check Now Available
Status check transactions allow a Merchant to validate a card with the Card Issuer, without holding funds on the card. This transaction type is ideal when saving a card for future charges. Note: Not all Acquiring Banks support status check transactions. Contact Paymark on click@paymark.co.nz to confirm if your Acquiring Bank supports status check transactions.
Online EFTPOS Autopay Now Available
Eligible Merchants using the Paymark Click hosted web payment page can save Online EFTPOS as a payment method for future payments. Contact Paymark on click@paymark.co.nz if you wish to enable this feature.
Merchant Hosted Tokenise Method Now Available
For Merchants processing payments from their own web site (“two party payment”), a “blind store” function is now available. This method allows Merchants to store the card for future payments, without validating card details with the card issuer.
IVR Specification Now Available
The Paymark Click IVR specification is now available here.
Paymark Click can take payments and store cards for later use via an Interactive Voice Response (IVR) that is integrated to your own IVR or telephony platform. The Click IVR is offered as a bespoke implementation. Should you with to integrate with the Click IVR, please contact Paymark on click@paymark.co.nz to discuss options.
Short Life Payment Page
The Click API now allows you to control how long the payment page is valid for. This is useful when you have other processes, such as shopping carts, that expire in less than one day (the default validity for a Click payment page).
You can contact Paymark to set this up for you.
Authorisation Cancellation Now Available
The Click API now supports cancellation transactions. This method allows Merchants to cancel a previously made, successful, authorisation transaction that is no longer required, for example, because the order cannot be fulfilled.
Note: Cancellations will only be actioned for Merchants using an Acquiring Bank that supports cancellation transactions.
Self Generated API Passwords
You can now generate your own API passwords that are part of your API credentials. Follow the instructions you received in your activation email. Or go into the Merchant Portal, navigate to the “Web Payments” section via the left-hand menu, then select “Integration Settings”.
Merchant Portal
The Click Merchant Portal has changed locations: the new location is https://client.paymarkclick.co.nz/.
The Click Merchant Portal user guide can be found by clicking “Page Help” in the top right hand corner of any Merchant Portal page.
The latest Merchant Portal feature releases are described below.
See Which Merchant Portal User Did a Transaction
You can view which logged in user did a transaction in the Merchant Portal, enabling any follow up with the appropriate person.
For Virtual Terminal transactions, the details are shown in the payment transaction details, under “User”. Where the “user” was “System”, this indicates an API transaction.

For refunds and captures done in the Merchant Portal, the details are shown in the refund / capture transaction details (remember to tick “Show Refund Transactions” or “Show Capture Transactions” when finding the transaction).

Time Included in Exported Transactions
When you export transactions from the Merchant Portal, the export includes the time of the transaction, enabling you to filter and query more easily.

Maximum Date Range Search 31 Days
When using a date range search, the maximum you can search is 31 days. This is to manage system response times. If you need to search a longer period, simply do multiple searches.
No Default Account in Virtual Terminal
When you make a payment through Virtual Terminal, you now need to select the Account you wish to put the payment against. When you have more than one account this prevents you accidentally putting the payment against the wrong account.

Settlement Report for a Specific Account
If you have multiple accounts under one Click Client ID, and these settle into different bank accounts, you can run a settlement report for each (Click) account to assist with bank account reconciliation.


No Limit on Viewing Historical Transactions
You can now view transactions for any date in the Merchant Portal (in maximum 31 days chunks). Note: You can only refund transactions that are less than six months old.
Automatically Assign New Accounts to Users with Specific Roles
For Merchant Portal Users that need access to all Accounts, for example, Contact Centre or Finance Users, any new Accounts can be automatically assigned to these Users overnight. This is based on the User’s Role in the Merchant Portal.
Please contact Paymark to set this up. We will need to know the Role name that you are using for these Users.
Additional Security on Invoice Payments Function
The “Invoice Payments” option (under Web Payments) now has additional security settings:
-
Reference, particulars and amount details that you set cannot be edited by the Cardholder.
-
The link you generate is valid for 24 hours (and this can be shortened if that meets your business needs).

Need More Help?
There is now a “Support” option in the left hand menu if you need more help using the Merchant Portal.
Revision History ¶
Date | Update |
---|---|
24 January 2017 | Added Direct Post information. |
3 February 2017 | Added Online EFTPOS payment request information. General maintenance. |
16 March 2017 | Added Tokenise and Authorisation options for “type” in Standard Payment. |
11 January 2018 | Added support for partial and full capture transactions. |
12 April 2018 | return_url now optional. Updated feature releases. |
20 April 2018 | Updated feature releases. |
22 May 2018 | Added cancellation API details. Fixed broken links. Updated feature releases. |
11 July 2018 | Updated feature releases. |
17 July 2018 | Added Merchant Hosted Transaction Processing method for creating Merchant tokens. |
27 September 2018 | Added IVR specification. |
21 December 2018 | Added Store Card Details without Issuer Validation API method. |
21 January 2019 | Updated authentication method for IVR Transaction Status Retrieval method. |
26 March 2019 | storeCard parameter in Merchant Hosted transaction processing is optional. |
4 April 2019 | Added payment token details (supporting Online EFTPOS Autopay). |
15 April 2019 | Added status check transaction details. |
3 May 2019 | Added Westpac Online EFTPOS details. |
11 June 2019 | Overhaul of marketing token section. |
6 August 2019 | Updated Westpac Sandbox transaction outcomes. |
11 December 2019 | Corrected error status for transaction search |
9 January 2020 | URL parameter request examples updated for consistency |
28 January 2020 | Update merchant hosted marketing token fields names to match actual API output.Removed broken user guide link |
22 September 2020 | Added acsTransactionId field to Retrieve Transaction response model. |
9 February 2021 | Added Click Magento plugin information |
Generated by aglio on 22 Feb 2022