Back to top

Paymark Click APIs

Introduction

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:

  1. 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).

  1. 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.
  1. 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 Standard Payment

  • Direct Post

You can select the option that best suits your integration requirements.

Both integration models support Online EFTPOS payments. Paymark Hosted Standard Payment 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 Standard Payment integration model. To use 3DS under Direct Post, additional development is required.

See also Merchant Hosted Transaction Processing for a further alternative.

Paymark Hosted Standard Payment: 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. Note: iFrames are not supported in the Paymark Hosted Payment Page. If you intend you use iFrames, you need to use the Direct Post model.

Full details are shown in the Paymark Hosted Standard Payment 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.

Paymark Hosted Standard Payment

Overview

https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest

The Standard Payment service allows your web app to register a payment, authorisation or tokenise request, which in turn will generate a unique URL that the application can use to load a secure payment page (Paymark Click hosted web payment page (“three party payment”)).

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)

  • Tokenise card (store card for future payments)

  • Create a secure token for future Online EFTPOS payments (done as part of an initial Online EFTPOS payment)

Transaction details may be retrieved by ID or by Merchant reference (Particular or Reference variables).

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 Paymark Click hosted web 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).

Two Return Options

The Web Payments API supports two types of return options for a Standard Payment, which determine what happens after a transaction is completed:

  1. Post to Return URL.
  2. Display in Hosted Web Payment Page.

When returning back to the Merchant’s web site, the Cardholder/Account Holder experience will differ based on the option selected. This option is configured in your Paymark Click account.

To configure your account, log in to the Click Merchant Portal using the Username and Password from 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.

Once you have successfully logged in, navigate to the Web Payments section via the left-hand navigation menu, then select Integration Settings. In here you can select the preferred return option. Select Save Changes once complete.





Post to Return URL

This is the default option.

If this option is selected, the 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: If you choose to use this model, your return_url must have a valid SSL certificate to avoid the Cardholder/Account Holder’s browser prompting any security warning messages. The Paymark Click hosted web 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 (to the insecure page).

Display in Hosted Web Payment Page

If this option is selected, the transaction results are displayed on the Paymark Click hosted web payment page and the Cardholder/Account Holder will be presented with a “Return to Merchant” button to go back to the Merchant’s web site.

Merchants are required to retrieve the transaction results using the Retrieve Transaction function.

Transaction Flow for Paymark Hosted Standard Payment


CSS customisation for Hosted Web Payment Page

The Paymark Click hosted web 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.

Only the latest version of the hosted web payment page supports CSS customisation. If you’re running an older version and wish to customise your payment page, please also contact us via click@paymark.co.nz to discuss options.

Standard Payment 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 “_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
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
notification_url Additional URL where the transaction response will be sent to. This must be a publicly accessible URL. 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
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. 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
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 This field has been deprecated: it has been replaced by store_payment_token. This field is ignored if store_payment_token has been used in the request. 0 or 1 as to whether the option to store (tokenise) card details should be displayed upon a successful transaction. 0 = do not display (default), 1 = display option to store card for future use. If type is set to “tokenise”, the store_card parameter will be ignored. Optional Integer N/A
store_card_without_input This field has been deprecated: it has been replaced by store_payment_token. This field is ignored if store_payment_token has been used in the request. 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. If type is set to “tokenise”, the store_card_without_input parameter will be ignored. Optional Integer N/A
transaction_source “MOTO” or “INTERNET” to indicate the source of the transaction. Default value is “INTERNET”. 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&
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.

Standard Payment Request Result

Result Options

Result Description
Success https://< webpaymentsbaseurl >?q=<hosted payment page id>
Failure Returns REST error information in XML format. See REST Exceptions.

Success Result Parameters

Name Description Data Type
cmd Value set to _xclick to indicate Standard Payment integration. String
request Encrypted request data. String

The Paymark Click hosted web payment page URL returned will be wrapped in an XML element in string format. You will need to extract the Payment 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=5e274bfe878446a997e252b0c4189cc0

</string>

Output Fields for Post to Return URL Return Option

These output fields only apply if the Return Option is set to Post to Return URL (see Two Return Options section).

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, 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
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, American Express and Diners Club 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:

  1. Merchant’s application registers the payment request and obtains a Direct Post URL.
  2. 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.
  3. 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, 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 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 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, “DINERS” Diners Club, “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 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, “DINERS” Diners Club, “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 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, “DINERS” Diners Club, “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, “DINERS” Diners Club, “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, 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 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 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, DINERS_CLUB, 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>

https://secure.paymarkclick.co.nz/api/transaction/search?startDate=<startDate>&endDate=<endDate>&reference=<reference>&particular=<particular>&clientAccountID=<clientAccountID>

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

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 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, 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 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, 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 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 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, 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 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, Diners Club 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 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 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, 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 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:

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, DINERS_CLUB, 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, DINERS_CLUB, 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, DINERS_CLUB, 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, DINERS_CLUB, 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, DINERS_CLUB, 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.

  1. Ensure the Click return option is set to “Post to Return URL”. Note: This setting ensures your Customers return to your Shopify store once they have completed payment and you receive notification of the transaction.

  2. Access the Click Shopify plugin.

  3. The link will lead you to the login page. Login to your existing Shopify store.

  1. After logging in you will see the page prompting you to install Click. Select the button “Install payment provider”.
  1. You will be directed to the “Payments” settings page. Select the “Edit” button in the “Paymark Click” section.
  1. 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.

  • Select the payment methods you have been set up with. Note: It is important to only select those you have loaded with Paymark. If you attempt a transaction with another payment method your Customer will see an error. To check what is loaded you can contact Paymark on 0800 PAYMARK.

Shopify payments settings page:

Activation email:

Merchant Portal:

  1. After entering all Paymark Click settings, select the “Save” button.

  2. 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.

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, Diners Club 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, Diners Club 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, Diners Club 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, Diners Club 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, DINERS_CLUB, 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, DINERS_CLUB, 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, DINERS_CLUB, 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:

  1. Transaction Registration: Merchant system registers a transaction request with Click IVR.
  2. Transaction Processing: Paymark Click IVR collects card information and processes the transaction.
  3. 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, 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 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, DINERS, 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 Paymark 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/20 111 00 Successful
MasterCard 5290075430806729 12/20 111 01 Bank Declined Transactions
MasterCard 5538737873773631 12/20 111 05 Bank Declined Transactions
MasterCard 5265340072069809 12/20 111 12 Transaction Type Not Supported
MasterCard 5307995509923512 12/20 111 31 Bank Declined Transactions
MasterCard 5114996316783803 12/20 111 51 Insufficient Funds
MasterCard 5178468787602840 12/20 111 54 Expired Card
MasterCard 5510545567805243 12/20 111 91 Error Communicating with Bank (Check Card Details)
MasterCard 2221006789012347 12/20 111 00 Successful
MasterCard 2221005430806727 12/20 111 01 Declined
MasterCard 2221007873773638 12/20 111 05 Declined
MasterCard 2221000072069809 12/20 111 12 Declined
MasterCard 2221005509923510 12/20 111 31 Declined
MasterCard 2221006316783808 12/20 111 51 Declined
MasterCard 2221008787602848 12/20 111 54 Declined
MasterCard 2221005567805245 12/20 111 91 Declined
MasterCard 5391715789309969 12/20 111 10 Partial authorisation (half the requested amount is approved for an authorisation transaction)
MasterCard 3D Secure 5422882800700007 12/20 111 00 Successful
MasterCard 3D Secure 2239468872817471 12/20 111 00 Successful
MasterCard 3D Secure 2239464831923120 01/20 123 10 Partial authorisation (half the requested amount is approved for an authorisation transaction)
MasterCard 3D Secure 5257221203980330 01/20 123 00 Successful (blank AAV)
MasterCard 3D Secure 5573216845946050 01/20 123 00 Successful (blank AAV)
MasterCard 3D Secure 5583731329831220 01/20 123 00 Attempted Authentication (blank AAV)
VISA 4987654321098769 12/20 111 00 Successful
VISA 4929474753922860 12/20 111 01 Bank Declined Transactions
VISA 4539032811676621 12/20 111 05 Bank Declined Transactions
VISA 4886709226179775 12/20 111 12 Transaction Type Not Supported
VISA 4556989846299273 12/20 111 31 Bank Declined Transactions
VISA 4556989785924709 12/20 111 51 Insufficient Funds
VISA 4916146026583852 12/20 111 54 Expired Card
VISA 4929233907988775 12/20 111 91 Error Communicating with Bank (Check Card Details)
VISA 4556286124462032 12/20 111 10 Partial authorisation (half the requested amount is approved for an authorisation transaction)
VISA 3D Secure 4918914107195005 12/20 111 00 Successful
VISA 3D Secure 4988721001931418 12/20 111 00 Card Not Enrolled
American Express 345678901234564 12/20 1111 00 Successful
American Express 372230337931151 12/20 1111 01 Bank Declined Transactions
American Express 374991708241573 12/20 1111 05 Bank Declined Transactions
American Express 371142424142835 12/20 1111 12 Transaction Type Not Supported
American Express 379864718969977 12/20 1111 31 Bank Declined Transactions
American Express 377799096385150 12/20 1111 51 Insufficient Funds
American Express 379269138331578 12/20 1111 54 Expired Card
American Express 375811155501015 12/20 1111 91 Error Communicating with Bank (Check Card Details)
Diners Club 36129543212349 12/20 NA 00 Successful
Diners Club 36913546454523 12/20 NA 01 Bank Declined Transactions
Diners Club 36708739256119 12/20 NA 05 Bank Declined Transactions
Diners Club 36627732834435 12/20 NA 12 Transaction Type Not Supported
Diners Club 36802790534777 12/20 NA 31 Bank Declined Transactions
Diners Club 36637566233778 12/20 NA 51 Insufficient Funds
Diners Club 36172562385513 12/20 NA 54 Expired Card
Diners Club 36888226794390 12/20 NA 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

Generated by aglio on 25 Jun 2020