Worldline NZ eCommerce APIs

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

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

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

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.

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

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/

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 transaction with card details

• Authorisation transaction with card details

• Status check transaction with card details

• Store card without Issuer validation

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.

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.

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

Standard response outputs are detailed in the Outputs section.

Possible Exceptions

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:

• Capture Transaction

• Cancellation Transaction

• Purchase with Card Token

• Authorisation with Card Token

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.

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

Standard response outputs are detailed in the Outputs section.

Possible Exceptions

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:

• Purchase with Card Token

• Authorisation with Card Token

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.

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

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:

• Purchase with Card Token

• Authorisation with Card Token

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.

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

Possible Exceptions

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

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 ¶

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

Search for Transactions ¶

Input Fields

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

Possible Errors and Exceptions

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.

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.

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

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.

Example:

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

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"originalTransactionId":"P160110000014131"
}

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:

• Purchase transaction with card details

• Capture transaction

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.

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

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 transaction with payment token

• Authorisation transaction with payment token

• Status Check transaction with payment token

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.

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

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.

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

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.

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

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

Token Management ¶

Overview ¶

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

• Retrieve card details using card token

• Retrieve payment method details using token reference

• Retrieve card details using token reference

• Update card token information

• Remove a card token

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.

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=

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.

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=

Possible Exceptions

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.

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.

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

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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.

Example:

GET https://secure.paymarkclick.co.nz/api/token/card/?tokenReference=TokenReference HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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.

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.

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

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.

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

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

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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

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

Result will return a list of transactions including the following elements:

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

Production: https://secure.paymarkclick.co.nz/api/token/merchanttoken/

Non-Production: https://uat.paymarkclick.co.nz/api/token/merchanttoken/

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.

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.

Result Options

Success Result Parameters

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

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

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

</string>

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

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.

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.

Result Options

Success Result Parameters

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.

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.

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.

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

Success Result Parameters

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.

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

Output Fields

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

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.

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.

Possible Errors and Exceptions

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.

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

Possible Errors and Exceptions

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.

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.

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 ¶

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.

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.

Card Numbers ¶

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