Worldline NZ eCommerce APIs

Introduction

This portal describes our eCommerce APIs for CLICK (cards) and Online EFTPOS (OPEN Banking)

We recommend you read this Introduction section in full before looking at specific API details.

The following APIs and services are described in this portal:

  1. Web Payments API:
  • Create a Hosted Payment Page.

  • Securely tokenise card details for later use.

  • Process a secure transaction from the Merchant’s web site.

  • Track payments made on a specific card (marketing token).


2. Transaction Processing API:
3. [Token Management](#manage-payment-and-card-tokens) API:
  • Retrieve payment token details 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.

Sign up for a demo/UAT account here.


You can test Hosted Payment Page in our [Web Payments sandbox](https://demo.paymarkclick.co.nz/guides/app/test/index.html).

End Points

The following end points are available for the Worldline NZ 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, Worldline NZ 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 Worldline NZ 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 Worldline NZ Client ID. Required String 50
password Your Worldline NZ API Password. Required String 50



Web Payments


Getting Started

Designed to take web-based card and Online EFTPOS payments by integrating your website or eCommerce platform. The Web Payments API is a RESTful API.


How Web Payments Work

Integration Models

The Web Payments API supports two integration models:

  • Custom Checkout

  • Hosted Payment Page

Select the intergration that best suits your requirements.

All integration models support Online EFTPOS. The Hosted Payment Page also supports Google Pay. Contact Worldline NZ if you wish to enable Online EFTPOS or Google Pay.

3Dsecure is supported under the Hosted Payment Page and Custom Checkout integrations.

Payment methods currently supported include MasterCard, Visa, American Express, and Online Eftpos. Card payments can benefit from 3DSecure more info here as well as Worldline NZ’s merchant-managed fraud tools.

See also Merchant Hosted Transaction Processing. Must be approved by Worldline NZ prior to integrating.


**Custom Checkout**

Custom Checkout is designed to give merchants more control over the payment experience. There’s no need to redirect customers to Worldline’s servers for processing, and as it uses iFrames containing hosted payment fields there is less PCI burden than doing a merchant-hosted API integration.

Custom Checkout is managed by a JavaScript plugin which you can use to create custom payment elements on your website. Worldline NZ handles all of the processing and provides merchants ways to customise the look and feel of the payment elements and the user experience of the payment flow.


**Hosted Payment Page**

This is the most commonly used option. HPP supports card, Online EFTPOS, and Google Pay payments.

With each payment request, an encrypted secure URL is returned to provide a hosted 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, payment is processed and the transaction results are made available to the Merchant site/service.

As the payment page is hosted by Worldline NZ, it minimises the Merchant’s PCI-DSS compliance requirements.

CSS customisation is supported to enable Merchant branding.

You can sign up for a demo account here. You can try out this integration option in our Web Payments sandbox.

Please talk to your acquiring bank about which integration type and transaction types you are considering. They will assess your site and advise Worldline NZ to enable your preferred option.




Custom Checkout

Click here to learn more about Custom Checkout




Hosted Payment Page


Overview

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

The Hosted Payment Page service allows your web app to register a payment, authorisation, status check or tokenise request, which will generate a unique URL that the application can use to load a secure payment page.

When setting up the card payment facility with your Acquiring Bank, you need to request the Gateway Hosted integration model. The Bank will then advise of your PCI compliance requirements.

The transactions available are:

  • Payment (purchase) (card, Online EFTPOS and Google Pay)

  • Authorisation (hold funds on a card for future charging)

  • Status check (validates card details with the issuing bank, no funds held or taken)

  • Tokenise card (store card for future payments without validating)

This service is a server to server communication method that validates all data posted to it. The payment request should be sent as a POST web request. All data should be provided in the body of the request formatted as a query string.

Once the request is received, the input will be validated and, if successful, a URL that can be used to access the hosted payment page will be returned. If an error occurs or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).


**Transaction Flow for Hosted Payment Page**

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


CSS customisation

The Hosted Payment Page offers a base CSS page that you can download and customise to change the look and feel of the page: https://secure.paymarkclick.co.nz/webpayments/shared/assets/v3/css/base.css.

Once you have updated the CSS, you can upload this for approval via your Merchant Portal (Production portal, Demo portal). We will review the CSS and publish it in that environment. Note: To ensure replication across all Worldline NZ servers, please ensure each version of the CSS file has a different name e.g. include a date or version number in the file name.


Request Data

The following table shows the input fields that can be posted to the Hosted Payment Page API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional. There are two custom fields reference and particular.

Name Description Required Type Length
username Your Worldline NZ Client ID. Required String 50
password Your Worldline NZ API Password. Required String 50
account_id Your Worldline NZ Account ID. Required Integer N/A
cmd Defines the Web Payments integration service to use. Always use “_xclick” for a HPP request. Required String N/A
amount The transaction amount in NZD. Must be a positive value (more than zero) for purchase or authorisation requests. Ignored (and may be omitted) for “status check” requests. Ignored (but must be provided) for “tokenise” requests. Required Decimal N/A
type Type of transaction requested, “purchase”, “authorisation” or “statuscheck”. Purchase is used to make a payment. Authorisation validates card details and holds funds on the card. Status check validates card details but does not hold any funds on the card; this is recommended for storing a card for future charges. A fourth option, “tokenise” is also available, however this does not validate card details. Required String N/A
reference Merchant defined value stored with the transaction. For Merchants accepting cards and Online EFTPOS, this should be a 12 character alphanumeric order identifier. This will appear on the Account Holder’s bank statement and is truncated at 12 characters, and any spaces or special characters will be removed. Optional String 50
particular Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , ? [ ] ( ) - _ Optional String 50
return_url The URL that the Cardholder/Account Holder will be sent to on completion of the payment. This must be a publicly accessible URL. (see Two Return Options section) to ensure the Customer is returned to the Merchant web site. Required String 1024
display_customer_email 0 or 1 as to whether to display the customer email receipt field. 0 = hide (default), 1 = display. Optional Integer N/A
store_payment_token Determines if the Customer’s payment method will be stored (tokenised) when the transaction is successful. 0 = do not display option to store payment method (default), 1 = display option to store payment method for future use, 2 = store payment method without asking Customer (Customer must have opted into storing the payment method on the Merchant’s web site). If type is set to “tokenise”, the store_payment_token parameter will be ignored. Optional Integer N/A
token_reference Merchant defined reference associated with the stored payment method (or card token). Allowed: alphanumeric, spaces, special characters @ # ’ " ; . \ / ! : , ? [ ] ( ) - _ Optional String 50

In addition, the following fields may be included for card transactions.
Name Description Required Type Length
merchant_token 0 or 1 as to whether a marketing token should be generated and returned upon successful completion of the payment. 0 = do not generate a marketing token (default), 1 = generate and return marketing token. Note: If 1 is used, it is expected the Cardholder has opted in to creating a marketing token elsewhere on the Merchant web site. Optional Integer N/A
transaction_source “MOTO” or “INTERNET” to indicate the source of the transaction. Optional String N/A
button_label Customise the text used on the “MAKE PAYMENT” button. Text will always be displayed in capitals. Allowed: alphanumeric, spaces, special characters $ , - ’ ! ? . # Optional String 20

Example:

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

Content-Type: application/x-www-form-urlencoded

account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
amount=10.00&
type=purchase&
reference=Reference&
particular=Particular&
display_customer_email=1&
store_payment_token=2&
token_reference=Account 12345&
button_label=PAY AND SAVE CARD
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference

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

Content-Type: application/x-www-form-urlencoded

account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
type=statuscheck&
reference=Reference&
particular=Particular&
display_customer_email=1&
store_payment_token=2&
token_reference=Account 12345&
button_label=SAVE CARD
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference

Note: Data is passed to the service as a URI query string so if a parameter contains URL punctuation characters it must be URL encoded. For example, reference=Ref?001 and particular=Part&001.


Response Data

Result Options

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

Example:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">

https://secure.paymarkclick.co.nz/api/webpayments/default.aspx?q=5e274bfe878446a997e252b0c4189cc0

</string>

Important

The Hosted Payment Page URL returned will be wrapped in an XML element in string format. You will need to extract the URL and redirect the customer to it. The customer will then enter their payment details directly into the Hosted Payment Page for processing.


Transaction Result

Transaction results, along with a set of other parameters, will be posted back to the Merchant’s return_URL. At the same time, the customer will be redirected back to the required return_URL.

For security and reliability reasons, Merchants are required to retrieve and validate the transaction results using the Retrieve Transaction function and not rely on the return post variables received in the return_URL.

Note:

Your return_url must have a valid SSL certificate to avoid the customer’s browser prompting any security warning messages. The hosted payment page is a secure page. If the web page referenced in the return_url is not secure, most browsers prompt the customer not to continue.


**Output fields for post to return_URL**

The following table shows the output fields to be posted back to the return_URL, along with a brief description of each.

Name Description Type Length
TransactionId Worldline NZ defined unique transaction ID. String 8
Type Transaction type (PURCHASE, AUTHORISATION, STATUS_CHECK, OE_PAYMENT, TOKENISE). String 50
AccountId The Worldline NZ 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 Worldline NZ defined unique receipt ID. Integer 9
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. 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, Online EFTPOS.
USER_DECLINED = May appear when store_payment_token variable was set to 1. 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.
PROCESSING = awaiting Customer action for an Online EFTPOS payment.
String 100
TokenReference Merchant defined reference associated with the stored payment method. 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). 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 hosted payment page. String 100
MerchantToken The marketing token registered 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 website. For example:

  • SUCCESSFUL: payment has been processed.

  • DECLINED: the Bank declined the payment.

  • CANCELLED: the customer cancelled the payment.




Merchant Hosted Transaction Processing


Overview

https://secure.paymarkclick.co.nz/api/transaction/


Please contact Worldline NZ before testing this integration type.
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 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. The Bank will assess your site and advise Worldline NZ.

Supports Online EFTPOS.

Does not support 3Dsecure.

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 Worldline NZ 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: Click does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. Optional String 50
cardNumber Card number without spaces. Numeric format. Required String 12-19
cardType Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express. 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. 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, 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 Worldline NZ 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” or “Recurring” Required String N/A
surchargeOverride If you do not want the pre-configured surcharge to be applied, you can alter the surcharge amount using this field. Setting it to 0 will apply no surcharge. Any positive decimal value provided in this field will be applied. e.g. to surcharge $1, send 1.00 Optional Decimal 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 Worldline NZ 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: Worldline NZ does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. Optional String 50
cardNumber Card number without spaces. Numeric format. Required String 12-19
cardType Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express. 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. 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 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” or “Recurring”. Required String N/A
surchargeOverride If you do not want the pre-configured surcharge to be applied, you can alter the surcharge amount using this field. Setting it to 0 will apply no surcharge. Any positive decimal value provided in this field will be applied. e.g. to surcharge $1, send 1.00 Optional Decimal 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.

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 Worldline NZ 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: Worldline NZ does not send any information to the Cardholder for transactions done through the Merchant Hosted Transaction Processing API. If not required, leave blank. Optional String 50
cardNumber Card number without spaces. Numeric format. Required String 12-19
cardType Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express. 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. 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 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” or “Recurring”. Required 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.

The recommended method is now Status Check, which validates card details without holding funds on the card.

A card token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.

See also:

Input Fields

The following table shows the input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Name Description Required Type Length
cardNumber Card number without spaces. Numeric format. Required String 12-19
cardType Card type. Accepted values are: “MC” MasterCard, “VISA” Visa, “AMEX” American Express. 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. 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). 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.


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 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 Worldline NZ 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 Worldline NZ 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). 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 Worldline NZ 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



3Dsecure

Overview

3Dsecure 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 as “Mastercard Securecode” and “Verified by Visa” (VbV).

With 3DSecure transactions, a Cardholder may be asked to authenticate during a transaction by entering Cardholder specific information, such as a pre-configured password or one time password. This is authenticated by the Cardholder’s Issuing Bank.

3DSecure also provides a level of chargeback protection for participating Merchants under certain conditions.


Enabling 3DSecure

Please contact your Acquirer Bank for 3DS enrolment. Your Acquirer Bank will complete your enrolment and send Worldline NZ an activation notice with 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.


3DSecure with Hosted Payment Page

For Hosted Payment Page, Worldline NZ handles the entire flow of the 3DS process and no specific development is required.


Possible Errors and Details

Possible 3DS errors are detailed in error codes 270-272 under Response Codes and Messages.

You can see 3DS information for card transactions under “Transactions Details” in the Merchant Portal. You can see whether 3DS was used and what the authentication result was.

Learn more about 3DS here (https://developer.paymark.co.nz/click-3ds2/#top)




Retrieve Transaction


Overview

Once the transaction has been processed the results can be retrieved and validated using one of the methods below. You can retrieve the transaction by transaction ID, reference, or particular.

The Transaction Processing API is a RESTful API over HTTP, with a JSON payload.


Methods

Transaction requests must be sent as a GET request. 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 (not the body) 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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, this is the surcharge amount for this transaction. Note: Contact Worldline NZ 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). String 50
cardNumber Masked card number showing first 6 and last 4 digits of the card. String 100
cardExpiry Expiry date of the card. Format MMYY. String 100
cardHolder The Cardholder name entered into the hosted web payment page. String 100
cardStored Whether or not the card was stored, false = not stored, true = stored. Always false for Online EFTPOS payments. Boolean 10
cardToken Payment token ID if a payment 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 510
tokenReference Merchant defined reference associated with the payment token used in this transaction, if the payment method associated with this token is a card. String 50
merchantToken The marketing token registered with Worldline NZ for the card used for this transaction. Only available if the merchantToken variable was set to 1. String 100
payerId Consumer’s personal identifier for Online EFTPOS payments. String 100
payerIdType Type of payerId that was used for Online EFTPOS payments. String 100
bank Consumer bank to which the Online EFTPOS payment request was sent. String 100
authenticationReference Transaction ID for 3DS 2. Can be used as threeDSRequestorInformation.priorAuthenticationInfo.reference in future 3DS 2 transactions for this cardholder. String 50

**Possible Errors and Exceptions**
HTTP Response Code Error Number Error Message
404 Not Found 5019 Transaction not found.
401 Unauthorised 3000 Authentication error. Username and/or Password are incorrect.
500 Internal Server Error -1 Unspecified error, contact Paymark.

Search for Transactions

Input Fields

Name Description Required Type Length
startDate Starting date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. Required Datetime N/A
endDate Ending date and time of transaction date to be included in the search result, inclusive. Date range cannot be more than 1 year. Required Datetime N/A
reference Reference value which transaction reference should match exactly to be included in the result. Optional String 50
particular Particular value which transaction reference should match exactly to be included in the result. Optional String 50
clientAccountId Client Account ID under which transaction should be searched for. If empty, method will search for all transactions under the merchant. Optional Integer N/A

Example:
GET https://secure.paymarkclick.co.nz/api/transaction/search?
    startDate=2017-08-01T00:00:00&
    endDate=2017-08-02T00:00:00&
    reference=Click-Test-Reference&
    particular=Click-Test-Particular&
    clientAccountId=7012345
    HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

**Result Options**
Result Description
Success 200 with body containing up to 100 transactions. For each returned transaction, details are the same as the output fields documented in Retrieve transaction by Transaction ID, ordered by transaction date in descending order. Note if search result covers more than 100 records, only the latest 100 records are returned. Therefore, an appropriate combination of parameters should be considered to restrict the search range.
Failure See exceptions and errors below.

Possible Errors and Exceptions

HTTP Response Code Error Number Error Message
400 Bad Request 7004 Start date cannot be greater than End date, please consult the payment web service integration manual.
400 Bad Request 7005 Date range greater than 1 year, please restrict the date range, please consult the payment web service integration manual.
400 Bad Request 7002 Reference cannot contain more than 50 characters, please consult the payment web service integration manual.
400 Bad Request 5019 Particular cannot contain more than 50 characters, please consult the payment web service integration manual.
400 Bad Request 6023 Client Account ID provided is not valid.
401 Unauthorised 3000 Authentication error. Username and/or Password are incorrect.
500 Internal Server Error -1 Unspecified error, contact Worldline NZ.



Capture Transaction


Overview

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

Merchants can capture the funds from a successful card authorisation transaction. Will need to pass the authorisation transaction ID and the $amount. This can be less than or equal to, but never more than, the total authorisation transaction amount.

Notes:

  • Authorisations should be finalised through a capture or a cancellation. Otherwise they will expire after roughly 7 days, depending on the card issuer.

  • Cancelled authorisations 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ defined unique receipt ID. Integer 9
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). 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 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 token used in this transaction, if the payment method associated with this token is a card. String 100
merchantToken The marketing token registered 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


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

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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ defined unique receipt ID. Integer 9
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). 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 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 token was 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 6
tokenReference Merchant defined reference associated with the payment token used in this transaction. String 100
merchantToken The marketing token registered with Worldline NZ 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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). 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 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 token used in this transaction, if the payment method associated with this token is a card. String 100
merchantToken The marketing token registered 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.

Token Transaction Processing

Overview

The Token Processing API allows a Merchant to use payment tokens to process transactions. A payment token allows Merchants to initiate a payment without requiring the Cardholder to enter any additional information to approve the payment.

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 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 and have an existing payment 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 Worldline NZ 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 Card token purchases only. Indicates whether this is a single or a recurring transaction. 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”. Required String N/A
transactionSourece Card token purchases only. Indicates where the transaction request was generated. Set to “Internet” when the cardholder initiates the transaction from a website or app. Set to “MOTO” when the cardholder initiates the transaction over the phone or by giving you card details offline. Set to “Merchant” when the merchant initiates the transaction using stored card details. Allowed: “Internet”, “MOTO” or “Merchant”. Required String N/A
agreementId Card token purchases only. Must be included when transactionFrequency is not “Single”. Identifies an agreement between the cardholder and the merchant, for the merchant to initiate transactions using a specific card on the cardholder’s behalf. Conditional String 50
surchargeOverride Card token purchases only. If you do not want the pre-configured surcharge to be applied, you can alter the surcharge amount using this field. Setting it to 0 will apply no surcharge. Any positive decimal value provided in this field will be applied. e.g. to surcharge $1, send 1.00 Optional Decimal N/A

Example:

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":"Recurring",
"transactionSource":"Merchant",
"agreementId":"123456789"
}

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.

For a full list of REST exceptions, refer to the REST Exceptions section.

Authorisation with Payment 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 Worldline NZ 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. 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. “”.
Required String N/A
surchargeOverride Card token purchases only. If you do not want the pre-configured surcharge to be applied, you can alter the surcharge amount using this field. Setting it to 0 will apply no surcharge. Any positive decimal value provided in this field will be applied. e.g. to surcharge $1, send 1.00 Optional Decimal 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.

Status Check with Payment Token

This method allows Merchants to make a status check transaction using previously stored card data. To use this method, the Merchant must have already stored the card in Click and have an existing payment 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 Worldline NZ issued Account ID. Required Integer 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. 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. “”.
Required String N/A

Example:

POST https://secure.paymarkclick.co.nz/api/transaction/statuscheck/6971410 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"accountId":700152,
"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 Worldline NZ 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 Worldline NZ 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 Worldline NZ defined unique receipt ID. Integer 9
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). 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 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 token used in this transaction, if the payment method associated with this token is a card. String 100
merchantToken The marketing token registered 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



Token Management


Overview


Tokens are ideal for websites or services that need to securely store card payment details for future purchases or recurring billing purposes. See also [Token Transaction Processing](#token-transaction-processing).

The Token Management API is available for managing existing stored tokens: payment method details 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 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. 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). 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.
Token Not Found The payment token passed in is not found or is invalid.

For a full list of REST exceptions, refer to the REST Exceptions section.


Retrieve Card Details Using Card Token

This method provides the functionality to retrieve the details of a stored card using the token identifier, when the card was stored using the “store card” method.

Only partial details for the card will be retrieved, and this is not sufficient to perform a transaction. The purpose of this method is for information only.


**Input Fields**

The token identifier is passed in as part of the URL.

Example:

GET https://secure.paymarkclick.co.nz/api/token/card/6971410 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

**Output Fields**
Name Description Type
cardDetails Details of the card. See table below for UDT structure. UDT
Name Description Type Length
cardToken Token identifier for the card. String 100
tokenReference Merchant defined reference associated with the stored card token. String 100
cardNumber Masked card number showing first 6 and last 4 digits of the card. String 50
cardType The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). String 100
cardHolder The Cardholder name initially collected from the secure payment page. String 100
cardExpiry Expiry date of the card, in format MMYY. String 100

Possible Exceptions

Exception Description
Authorization Exception Username and password are not correct or the web service is not available to you.
Card Token Not Found The card token passed in was not found or is invalid.

For a full list of REST exceptions, refer to the REST Exceptions section.


Retrieve Payment Method Details Using Token Reference

This method retrieves the details of all stored payment methods with the token reference that matches the parameter passed. The token type (card or OE) may be passed as an optional parameter.

Only partial information is returned, and this is not sufficient to perform a transaction. The purpose of this method is for information only.


**Input Fields**

The following table shows the input fields that can be posted to the Token Management API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Name Description Required Type Length
tokenReference URL encoded value of the token reference the returned tokens must have. This is not case sensitive. If left empty, payment tokens with no token reference will be returned. Required String 50
tokenType The type of payment token to be searched: CARD or OE. Optional String N/A
startDate Earliest date the token was created (inclusive of datetime specified). Optional Datetime N/A
endDate Latest date the token was created (inclusive of datetime specified). Optional Datetime N/A

Example:
GET https://secure.paymarkclick.co.nz/api/token/payment/?tokenReference=TokenReference&tokenType=OE HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

**Output Fields**
Name Description Type
tokenDetails Array Details of the payment tokens with this token reference. See table below for UDT structure. UDT
Name Description Type Length
tokenType Indicates the payment method this token is for. String N/a
token Token identifier. String 100
tokenReference Merchant defined reference associated with the stored payment token. String 100
tokenDetails Details of the payment method. See table below for UDT structure. UDT N/a

**Token Details for Card Payment Method**
Name Description Type Length
cardNumber Masked card number showing first 6 and last 4 digits of the card. String 50
cardType The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD). String 100
cardHolder The Cardholder name initially collected from the secure payment page. String 100
cardExpiry Expiry date of the card, in format MMYY. String 100

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




Magento Plugin


Overview

Worldline NZ offers a free Magento plugin allowing you to take payments from a Magento 2.x store via a Hosted Payment Page.


Set Up Worldline NZ account

We recommend setting your site up with a demo account, so that you can test the integration before going live and processing real payments.


Install Magento plugin

You can install the Magento plugin via Composer, using the following command:

composer require paymark/click

Alternatively download the package from GitHub and put the files into this folder in your Magento directory: app/Paymark/PaymarkClick

Once the plugin has been installed, run these two commands to enable the plugin:

#enable the plugin
php bin/magento module:enable Paymark_PaymarkClick

#run magento setup
php bin/magento setup:upgrade

Configure Magento plugin

After the module has been installed go to Stores > Settings > Configuration > Sales > Payment Methods in the Magento Admin to find the configuration options.

The configuration options are as follows:

  • Title: Title that will appear on the checkout page

  • User ID: User ID for your Worldline NZ account (You can find this in your merchant console after registering)

  • Password: Password for your Worldline NZ account (You can set this in your merchant console after registering)

  • Account ID: Worldline NZ account id (You can find this in your merchant console after registering)

  • UAT: Flag to alternate UAT environment - this changes the payment URL

  • Debug Log: Write logs to paymark.log during the checkout process for debugging purposes

  • Payment Action: Option to either do an Authorisation charge or a full Capture (Worldline NZ will need to enable the Authorisation option if you want to use this instead)


Go live

When you are ready to go live, you can register for a production Worldline NZ account from your demo merchant console. Once your production account is set up, change the user ID, Password and Account ID to your production values and update the UAT flag in Magento so that your site is connected to your production account.

You’re now ready to accept payments online.




Reporting Service


Overview

https://secure.paymarkclick.co.nz/api/report/transaction

By using the reporting service, Merchants can query and obtain a list of transactions that meet the input criteria.

The Reporting Service API is a RESTful API over HTTP, with a JSON payload.


Method Options

Requests should be sent as a GET web requests. Input data should be provided as part of the URL request. Once the request is received the input will be validated and, if successful, response will be returned in JSON format with body containing information for the requested transactions.

Authentication is achieved by passing an encoded username and password in the HTTP header (not the body) 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, STATUS_CHECK. 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 Worldline NZ 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, STATUS_CHECK, REFUND, CAPTURE, OE_PAYMENT). String 50
accountId Worldline NZ 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 Worldline NZ defined unique receipt ID. Integer 9
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 Worldline NZ to configure a surcharge. 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). 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 hosted payment page.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 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 Worldline NZ.



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 Worldline eCommerce can be tracked, providing an omnichannel facility for Merchants. Marketing tokens are supported for transactions through the HPP and Merchant Hosted Transaction Processing. Note: Not available for Online EFTPOS.

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). A marketing token can also be created for an EFTPOS card to track all transactions made with that card via EFTPOS terminals.

Worldline NZ is used to register and manage marketing tokens using the “Merchant Token” services.


End Points

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 feature. To sign up to use this facility, please contact Worldline NZ 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 page to register the marketing token. For standard cards, that is, Visa, MasterCard, American Express, the Hosted Payment Page 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.

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 Transaction Processing API. For standard cards, that is, Visa, MasterCard, American Express, 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 Hosted Payment Page integration, the Web Payments API supports only the Post to return_URL 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.

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 Worldline NZ Client ID. Required String 50
password Your Worldline NZ 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 Worldline NZ Client ID. Required Integer N/A
account_id Your Worldline NZ 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, EFTPOS). String 50
cardNumber Masked card number showing first 6 and last 4 digits of the card. String 100
merchantToken The marketing token registered 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

**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 Worldline NZ Client ID. Required String 50
password Your Worldline NZ API Password. Required String 50
cmd Defines the Web Payments integration service to use. Required String N/A
client_id Your Worldline NZ Client ID. Required Integer N/A
account_id Your Worldline NZ 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 Worldline NZ Client ID. Required String 50
password Your Worldline NZ API Password. Required String 50
account_id Your Worldline NZ 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 Worldline NZ Client ID. Required Integer 8
cardExpiry Card expiry date, in the format MMYY. E.g. 0520 for May 2020. Numeric format. Expiry dates in the past are allowed as long as the format is correct. Required for standard card types. Ignored for EFTPOS cards. Required String 4
cardNumber Card number without spaces. Numeric format. Required String 12-19
reference Merchant defined reference associated with the marketing token. Allowed: alphanumeric, spaces, special characters _ - ’ ! @ # $ & * ( ) + \ { } : " , . / Optional String 50
particular Merchant defined value stored with the transaction. Allowed: alphanumeric, spaces, special characters @ # ’ & " ; . \ / ! : , + ? [ ] ( ) - _ Optional String 50

Example:

POST https://secure.paymarkclick.co.nz/api/token/merchanttoken/ HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
    "accountId":"700152",
    "cardExpiry":"0520",
    "cardNumber":"4987654321098769",    
    "reference":"Reference",
    "particular":"Particular",
}

Possible Errors and Exceptions

HTTP Response Code Error Number Error Message
400 Bad Request 2003 Invalid account ID.
400 Bad Request 1004 Card expiry must be in the correct format: MMYY.
400 Bad Request 1002 Card number must be a valid credit card number.
400 Bad Request 50001 Reference must be no more than 50 characters in length.
401 Unauthorised 3000 Authentication error. Username, Account ID and/or password are incorrect.
401 Unauthorised 3001 Authentication error. Service restricted or unavailable.
500 Internal Server Error -1 Unspecified error, contact Paymark.

Output Fields

The following table shows the output fields along with a brief description of each.

Name Description Type Length
merchantToken The marketing token registered with Paymark for the card used for this transaction. String 100
cardNumber Masked card number showing first 6 and last 4 digits of the card. String 100
cardType The card type used for this transaction (MASTERCARD, VISA, AMERICAN_EXPRESS, QCARD, EFTPOS). String 50
reference Merchant defined reference associated with the marketing token. String 100
particular Particulars used for the transaction, as defined by the Merchant. String 100
cardExpire Card expiry date, in the format MMYY. E.g. 0520 for May 2020. Numeric format. String 4
createdDate Date and time when marketing token was created. Datetime N/A

Retrieve Marketing Token Using Merchant Reference

This method provides the functionality to retrieve the details of the marketing token using the Merchant’s reference provided when the token was registered.

Input Fields

The following table shows the input fields that can be posted to the Merchant Token API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Name Description Required Type
reference Reference for the marketing token to be found. Required String
startDate Starting date and time of registration transaction date to be included in the search result, inclusive. Optional Datetime
endDate Ending date and time of registration transaction date to be included in the search result, inclusive. Optional Datetime

Example:

GET https://secure.paymarkclick.co.nz/api/token/merchanttoken/?
    reference=Reference&
    startDate=2017-08-01T00:00:00&
    endDate=2017-08-02T00:00:00&
    HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Output Fields

The following table shows the output fields along with a brief description of each.

Name Description Type Length
merchantToken The marketing token registered 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, 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 Worldline NZ 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.



Merchant Web Site Requirements

When a Merchant processes payments from their own web site Merchant Hosted Transaction Processing (“two party payment”), the Merchant’s web site needs to comply with the following requirements.


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 authentication method. Worldline NZ reserves the right to ask the Merchant to implement CAPTCHA or a similar service.


Branding Requirements

The Worldline logo must always be displayed on the payment page. Please contact Worldline 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 (non 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”.




REST Exceptions


Overview

This section details the API error codes and messages that may be seen in the Worldline NZ 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 Worldline NZ.


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"
}

Hosted Payment Page Error Messages

The Hosted Payment Page 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>

Payment Service Errors

Error Number Error Message
-1 Unspecified Error - Contact Worldline NZ
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.
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 Worldline NZ 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 Worldline NZ 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 Worldline NZ 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 Worldline NZ APIs.


Transaction Responses and Error Messages

Once a transaction is submitted for processing, (no REST Exceptions have occurred) the transaction response returned will indicate the status. An error code and error message will be returned if not successful.

Status Response Code API Error Message Acquirer Response code(s)
Successful 200 Transaction Successful 00, 10, 85
Declined 200 Insufficient Funds 51, 61
Declined 201 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, 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 3DSecure 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 Transaction Locked (Please try 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 Online EFTPOS Trusted payments not allowed for this merchant. Either merchant is not enabled for Trusted or the customer has revoked Trusted.
Failed 398 – 409 Invalid request. Trust already exists.
Merchant tried to set up Online EFTPOS Trusted 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 Worldline NZ.
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 non-production environment.

Important: Please ensure you do not use real card data within the non-production environment.


**Important:** Please contact Worldline NZ to confirm the latest up-to-date test cards.

Card Numbers

To process test transactions within the non-production environment you must use one of the cards listed below.

Card Type Card Number Card Expiry (MM/YY) CSC Response Code Transaction Status
MasterCard 5123456789012346 12/24 111 00 Successful
MasterCard 5290075430806729 12/24 111 01 Bank Declined Transactions
MasterCard 5538737873773631 12/24 111 05 Bank Declined Transactions
MasterCard 5265340072069809 12/24 111 12 Transaction Type Not Supported
MasterCard 5307995509923512 12/24 111 31 Bank Declined Transactions
MasterCard 5114996316783803 12/24 111 51 Insufficient Funds
MasterCard 5178468787602840 12/24 111 54 Expired Card
MasterCard 5510545567805243 12/24 111 91 Error Communicating with Bank (Check Card Details)
MasterCard 2221006789012347 12/24 111 00 Successful
MasterCard 2221005430806727 12/24 111 01 Declined
MasterCard 2221007873773638 12/24 111 05 Declined
MasterCard 2221000072069809 12/24 111 12 Declined
MasterCard 2221005509923510 12/24 111 31 Declined
MasterCard 2221006316783808 12/24 111 51 Declined
MasterCard 2221008787602848 12/24 111 54 Declined
MasterCard 2221005567805245 12/24 111 91 Declined
MasterCard 5391715789309969 12/24 111 10 Partial authorisation (half the requested amount is approved for an authorisation transaction)
MasterCard 3D Secure 5123450000000008 01/39 100 00 Successful
VISA 4987654321098769 12/24 111 00 Successful
VISA 4929474753922860 12/24 111 01 Bank Declined Transactions
VISA 4539032811676621 12/24 111 05 Bank Declined Transactions
VISA 4886709226179775 12/24 111 12 Transaction Type Not Supported
VISA 4556989846299273 12/24 111 31 Bank Declined Transactions
VISA 4556989785924709 12/24 111 51 Insufficient Funds
VISA 4916146026583852 12/24 111 54 Expired Card
VISA 4929233907988775 12/24 111 91 Error Communicating with Bank (Check Card Details)
VISA 4556286124462032 12/24 111 10 Partial authorisation (half the requested amount is approved for an authorisation transaction)
VISA 3D Secure 4508750015741019 01/39 100 00 Successful
American Express 345678901234564 12/24 1111 00 Successful
American Express 372230337931151 12/24 1111 01 Bank Declined Transactions
American Express 374991708241573 12/24 1111 05 Bank Declined Transactions
American Express 371142424142835 12/24 1111 12 Transaction Type Not Supported
American Express 379864718969977 12/24 1111 31 Bank Declined Transactions
American Express 377799096385150 12/24 1111 51 Insufficient Funds
American Express 379269138331578 12/24 1111 54 Expired Card
American Express 375811155501015 12/24 1111 91 Error Communicating with Bank (Check Card Details)

Generated by aglio on 14 Oct 2024