Paymark Click APIs

Web Payments ¶

Getting Started ¶

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

How Web Payments Works ¶

Integration Models

The Web Payments API supports two integration models:

• Paymark Hosted Payment Page

• Direct Post

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

Both integration models support Online EFTPOS payments. Paymark Hosted Payment Page also supports Google Pay payments. Contact Paymark if you wish to enable Online EFTPOS or Google Pay.

Three Domain Secure (3DS) is fully supported under the Paymark Hosted Payment Page integration model. To use 3DS under Direct Post, additional development is required.

See also Merchant Hosted Transaction Processing for a further alternative.

Paymark Hosted Payment Page: This is the most commonly used option. This supports card, Online EFTPOS and Google Pay payments. This model is the easiest to implement out of all the options.

With each payment request, an encrypted secure URL is returned to provide a Paymark Click hosted web payment page for that transaction. This page contains appropriate merchant and transaction details and the Cardholder/Account Holder is required to enter their card or account information to proceed. Once the Cardholder/Account Holder submits valid card or account details and payment is processed and the transaction results are made available to the Merchant site/service.

As the payment page is hosted by Paymark, it minimises the Merchant’s PCI-DSS compliance requirements. The payment page also supports some CSS customisation to enable Merchant branding.

Full details are shown in the Paymark Hosted Payment Page section.

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

Direct Post: This is designed to receive card or Online EFTPOS payer information in a direct URL post from any Merchant held payment page, without storing card or payer information in the Merchant’s system. This option reduces the Merchant’s PCI-DSS compliance requirements, while still giving the Merchant an option to use their own payment page if the Paymark Hosted Payment Page does not meet their needs. This is also the recommended method if the Merchant is using iFrames and does not require Three Domain Secure (3DS). Full details are shown in the Direct Post section.

If Direct Post is required, please talk to your Acquiring Bank. Your Acquiring Bank will assess your site and advise Paymark to enable this option accordingly.

Hosted Payment Page ¶

Overview ¶

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

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

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

The transactions available are:

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

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

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

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

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

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

Transaction Flow for Paymark Hosted Payment Page

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

CSS customisation ¶

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

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

Request Data ¶

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

In addition, the following fields may be included for card transactions.

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>

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

Transaction Result ¶

Transaction results, along with a set of other parameters, will be posted back to the Merchant’s return URL. At the same time, the Cardholder/Account Holder will be redirected back to the return URL.

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

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

Output Fields for Post to Return URL ¶

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

The following table shows output fields that may also be present for a card payment.

Note on Transaction Status

The status field in the transaction response enables you to manage the Customer experience in your web site. For example:

• SUCCESSFUL indicates the payment has been processed and you can fulfil the order.

• DECLINED means the Bank has declined the payment so you may wish to offer the Customer an alternative payment method.

• CANCELLED means the Customer cancelled out of the payment screen so you may wish to release any hold on goods that you have (pending payment).

Direct Post ¶

Overview ¶

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

The Direct Post service allows data from the Merchant hosted payment page to be securely sent to Paymark. Registering a payment request for Direct Post works in a similar way as Standard Payment. It allows the Merchant’s application to register a payment request and obtain a unique URL to which payment information can be posted.

When setting up the card payment facility with your Acquiring Bank, you need to request the Direct Post integration model. The Bank will then advise Paymark to enable Direct Post on your account. Direct Post requires a higher level of PCI compliance than Standard Payment. Your Bank will advise you of your specific requirements. For additional information, refer to the PCI DSS Self Assessment Questionnaires, A-EP information.

There are three options available for the transaction:

• Payment (card and Online EFTPOS)

• Authorisation (hold funds on a card)

• Tokenise (store card for future payments).

For card payments, the Cardholder may also choose to store their card details (thus generating a card token) at the same time as making the payment.

A card token is ideal for websites or services that wish to collect card details for recurring billing purposes in a secure manner. This only applies to standard card types: Visa, MasterCard and American Express cards.

This service is implemented by encrypting the card number and expiry date and assigning it a unique token that can then be used to process future transactions. If using type “authorisation”, the card details are validated at the time the card is stored through creating an authorisation for the amount specified in the direct post request.

The transaction result is retrieved by unique reference Result_ID. Other transaction details may be retrieved by ID or by Merchant reference (Particular or Reference variables). See also Retrieve Transaction section.

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

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

Transaction Flow ¶

There are three stages to the Direct Post transaction:

1. Merchant’s application registers the payment request and obtains a Direct Post URL.
2. Merchant’s payment page collects payment information and posts to the Direct Post URL. Paymark then processes the transaction and returns a unique reference Result_ID.
3. Merchant’s application retrieves the transaction result using the unique reference Result_ID.

Notes:

• Your return_url must have a valid SSL certificate to avoid the Cardholder/Account Holder’s browser prompting any security warning messages.

• Your site needs to be able to handle redirection to the Issuing Bank’s authentication site (Issuer ACS) if the Merchant is enabled for 3DS. C.f. 3DS with Direct Post Integration.

Direct Post Request Data ¶

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

In addition, the following fields are included for card payments.

Example:

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

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

account_id=700152&
username=90127&
password=Paymark123&
amount=10.00&
reference=Reference&
particular=Particular&
cmd=_xdirect&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference

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

Direct Post Request Result ¶

Result Options

Example:

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

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

</string>

Post Payment Details ¶

After a Direct Post URL has been obtained from above, a payment page on the Merchant’s web site can collect payment information and post it to the Direct Post URL. This may be card payment information or Online EFTPOS payment information. For specific requirements on the presentation and handling of Online EFTPOS payments, please also refer to the Online EFTPOS API specification or contact Paymark with any questions.

To process a card payment, the following fields are used for the post to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

To process an Online EFTPOS payment, the following fields are used for the post to the Web Payments API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

payerIdType and bankId Mapping

Supported Consumer Banks are:

• ASB (bank = ASB)

• Co-operative Bank (bank = COOPERATIVE)

• Heartland (bank = HEARTLAND)

• Westpac (bank = WESTPAC)

Each Consumer Bank can allow different types as the payerIdType. The table below shows what is allowed by each Consumer Bank (as specified in bankId).

Examples:

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

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

card_number=4987654321098769&
card_expiry_month=05&
card_expiry_year=17&
card_holder_name=Mr John Smith&
card_csc=111&
payment_method=CARD

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

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

payer_id=ABC.123456789
payer_id_type=WESTPAC1ID
bank=WESTPAC 
payment_method=OE

Output Fields

While the transaction is being processed, the Cardholder/Account Holder is redirected back to the Return URL that was in the transaction request, along with the Result_Id and a Transaction_No (for successful transactions).

Validating Transaction Result By Result_ID ¶

After a Result_ID is returned from the previous step, the Merchant application can retrieve the transaction result.

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

Example:

GET https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/QueryDirectPostResultByResultId?
username=90127&
password=Paymark123&
account_id=700152&
result_id=e619459a-3c03-478f-b0c1-44a680ef87cc
HTTP/1.1

Validate Transaction Request Result ¶

Result Options

Success Result Parameters

The following table shows output fields that may also be present for a card payment.

Merchant Hosted Transaction Processing ¶

Overview ¶

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

The Transaction Processing API allows a Merchant to process a secure card or Online EFTPOS payment from their own web site (“two party payment”).

With this option, Merchants are able to utilise their own functions and processes to collect and store card details, and then make a direct server to server API call to process transactions via the Paymark Transaction Processing API. Merchants also have the option of bulk processing transactions with pre-collected Card details. Having the ability to collect and store card details, Merchants are required to meet full PCI-DSS compliance.

If Merchant Hosted Transaction Processing is required, please talk to your Acquiring Bank. Your Acquiring Bank will assess your site and advise Paymark to enable the option accordingly.

This option supports Online EFTPOS payments. Contact Paymark if you wish to enable Online EFTPOS.

Merchant Hosted Transaction Processing currently does not support Three Domain Secure (3DS).

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

Method Options ¶

This API offers the following methods to process transactions:

• Purchase transaction with card details

• Authorisation transaction with card details

• Status check transaction with card details

• Store card without Issuer validation

• Payment transaction using Online EFTPOS

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.

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

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

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

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

Status Check with Card Details ¶

This method allows Merchants to make a status check transaction by passing in card data. A status check validates the card with the Issuer without the need to hold funds on the card. Not all Acquiring Banks support status checks: contact Paymark to confirm if your Acquiring Bank supports status checks.

The primary use for a status check is to store the card for future transactions. The card is stored (tokenised) and the token and token reference be returned with the transaction result. The next time a transaction is to be done on this card, the token can be used to process the transaction.

See also:

• 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. Contact Paymark to confirm if your Acquiring Bank supports status checks.

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

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

See also:

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

Online EFTPOS Payment ¶

This method allows Merchants to send a payment request to a Customer using Online EFTPOS.

Input Fields

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

payerIdType and bankId Mapping

Supported Consumer Banks are:

• ASB (bank = ASB)

• Co-operative Bank (bank = COOPERATIVE)

• Heartland (bank = HEARTLAND)

• Westpac (bank = WESTPAC)

Each Consumer Bank can allow different types as the payerIdType. The table below shows what is allowed by each Consumer Bank (as specified in bankId).

Example:

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

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"payerId": "0210123456",
"payerIdType": "MOBILE",
"bank": "ASB"
}

Output Fields

Standard response outputs are detailed in the Outputs section.

Possible Exceptions

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

Three Domain Secure ¶

Overview ¶

Three Domain Secure (3DS) is a payment card industry standard for authenticating a Cardholder performing an online purchase and is designed to provide greater online transaction security for both the Cardholder and the Merchant. It is marketed by Mastercard as “Mastercard Securecode” and by Visa as “Verified by Visa” (VbV).

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

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

Enabling 3DS ¶

If you wish to enable 3DS, please contact your Acquirer Bank for 3DS enrolment. Your Acquirer Bank will complete your enrolment and send Paymark an activation notice with all the required information.

Please note, if you use 3DS your website and integration method must support the use of sessions and cookies. For some newer web browsers, this means you may not be able to host the payment page in an iFrame.

3DS with Standard Payment Integration ¶

For Standard Payment integration, Click handles the entire flow of the 3DS process and no specific development is required for 3DS.

3DS with Direct Post Integration ¶

For Direct Post integration, Click handles the flow of the 3DS process. However, Cardholders will be redirected away from your website to the Issuing Bank’s authentication site to complete their card verification. The Cardholder will then be redirected back to your site. You need to make sure your website can handle this redirection in order for 3DS to work smoothly.

How 3DS works with Direct Post

Between the Direct Post Request Result and Post Payment Details steps, the Merchant is sent a HTML payload that can be used to invoke the Cardholder redirection to the Issuer’s 3DS authentication flow (Issuer ACS).

3DS with Merchant Hosted Integration ¶

3DS is not supported with Direct API integration via methods detailed under Merchant Hosted Transaction Processing. If you wish to implement this function, contact Paymark for further consultation.

Possible Errors and 3DS Details ¶

For both Standard Payment integration and Direct Post integration, Click handles 3DS processing. There are no additional inputs and outputs. Possible 3DS errors are detailed in error codes 270-272 under Response Codes and Messages.

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

Retrieve Transaction ¶

Overview ¶

Once the transaction has been processed the results can be retrieved and validated using one of the methods described below. Options are to retrieve the transaction by (Paymark) ID, or by (Merchant) reference or particular.

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

Method Options ¶

https://secure.paymarkclick.co.nz/api/transaction/search/<transactionID>

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

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

Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request.

If an error occurs, or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).

Retrieve Transaction by Transaction ID ¶

Input

Transaction ID is passed in as part of the URL and no other inputs are required for the request.

Example:

GET https://secure.paymarkclick.co.nz/api/transaction/search/P170310001234567 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

Result Options

Output Fields

Possible Errors and Exceptions

Search for Transactions ¶

Input Fields

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

Possible Errors and Exceptions

Capture Transaction ¶

Overview ¶

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

The Transaction Processing API allows a Merchant to capture (receive funds for) a previously created successful card authorisation transaction.

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

Capture Transaction ¶

This method allows Merchants to capture the funds from a previously made, successful, card authorisation transaction. In order to perform a capture you will need to pass the original (authorisation) transaction ID and the amount to capture. This can be less than or equal to, but never more than, than the original authorisation transaction amount.

See also:

• Standard Payment

• Direct Post

• Authorisation transaction with card details

• Authorisation transaction with card token

Notes:

• All authorisations need to be finalised, either through a capture or a cancellation.

• If an authorisation has already been cancelled, it cannot be captured.

Input Fields

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

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

Possible Exceptions

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

Cancellation Transaction ¶

Overview ¶

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

The Transaction Processing API allows a Merchant to cancel a card authorisation when this authorisation is no longer needed and the funds will never be captured.

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

Cancellation Transaction ¶

This method allows Merchants to cancel a previously made, successful, authorisation transaction that is no longer required, for example, because the order cannot be fulfilled. All authorisations need to be finalised, either through a Capture or a cancellation. In order to perform a cancellation you will need to pass the original (authorisation) transaction ID.

Note: If an authorisation has already been captured, it cannot be cancelled.

See also:

• Standard Payment

• Direct Post

• Authorisation transaction with card details

• Authorisation transaction 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/cancellation HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"originalTransactionId":"P160110000014131"
}

Output Fields

Possible Exceptions

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:

• Standard Payment

• Direct Post

• Purchase transaction with card details

• Purchase transaction with card token

• Payment transaction using Online EFTPOS

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

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

Possible Exceptions

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

Payment Token Transaction Processing ¶

Overview ¶

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

Click supports two types of tokens for financial transactions:

• Payment token, which supports multiple payment methods, including card payments and Online EFTPOS payments.

• Card token, a deprecated feature than can be used for cards only.

This section covers both types of tokens, and the functions available with each. If building a new integration with Click, we recommend using payment tokens to build longevity into your integration.

The Token Processing API allows a Merchant to use payment (card or Online EFTPOS) tokens to process transactions. A payment token allows Merchants to initiate a payment without requiring the Cardholder to enter any additional information (for card tokens), or Account Holder to approve the payment (for Online EFTPOS tokens).

A payment token can be created using the Paymark Click hosted web payment page (using the Standard Payment integration model). A payment token can be created for both card and Online EFTPOS payment methods. Cards that can be tokenised are: Visa, MasterCard, American Express and Q Card cards.

A card token may also be created through a Direct Post or Merchant Hosted payment page, the Click IVR, or the Click Merchant Portal.

This token processing feature can also be built into systems to create an automated, flexible processing system to suit business processes, for example, billing cycles.

This function is implemented by encrypting the payment details via an initial transaction and assigning it a unique token number which can then be used to process future transactions.

For information on managing existing payment or card tokens, see the Manage Tokens section.

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

Method Options ¶

This API offers the following methods to process token transactions:

• Purchase transaction with payment (or card) token

• Authorisation transaction with payment (or card token) (cards only)

Purchase with Payment (or Card) Token ¶

This method allows Merchants to make a purchase transaction using previously stored payment method data. To use this method, the Merchant must have already stored the payment method with Paymark and have an existing payment (or card) token.

Input Fields

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

Example:

POST https://secure.paymarkclick.co.nz/api/transaction/purchase/OE.1234567890 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular"
}

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

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
"accountId":700152,
"amount":10.00,
"reference":"Reference",
"particular":"Particular",
"transactionFrequency":"Single"
}

Output Fields

Standard response outputs are detailed in the Outputs section.

Possible Exceptions

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

Authorisation with Payment (or Card) Token ¶

This method allows Merchants to make an authorisation transaction using previously stored card data. To use this method, the Merchant must have already stored the card with Paymark and have an existing payment (or card) token.

Input Fields

The card token identifier (for the card to be authorised) is passed in as part of the URL. The following table shows the other input fields that can be posted to the Transaction Processing API. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

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.

Outputs ¶

All token transaction processing methods have a standard set of response outputs as described below.

Output Fields

Manage Payment and Card Tokens ¶

Overview ¶

https://secure.paymarkclick.co.nz/api/token/payment
https://secure.paymarkclick.co.nz/api/token/card

A payment token is ideal for websites or services that need to securely store payment details for future purchases or recurring billing purposes. See also Token Transaction Processing.

The Token Management API is available for managing existing stored tokens: payment method details (card and Online EFTPOS) can be retrieved, details for card tokens can be updated, and card tokens can be removed.

The Token Management API is a RESTful API over HTTP, with a JSON payload.

Method Options ¶

This API offers the following methods to manage card tokens:

• Retrieve payment method details using payment token

• Retrieve card details using card token

• Retrieve payment method details using token reference

• Retrieve card details using token reference

• Update card token information (for card tokens only)

• Remove a card token (for card tokens only)

Retrieve Payment Method Details Using Payment Token ¶

This method provides the functionality to retrieve the details of a stored payment method (card or Online EFTPOS) using the token identifier.

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

Input Fields

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

Example:

GET https://secure.paymarkclick.co.nz/api/token/payment/OE.1234567890 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Output Fields

Token Details for Card Payment Method

Token Details for Online EFTPOS Payment Method

Possible Exceptions

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

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.

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/payment/?tokenReference=TokenReference&tokenType=OE HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Output Fields

Token Details for Card Payment Method

Token Details for Online EFTPOS Payment Method

Possible Exceptions

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=

Output Fields

Possible Exceptions

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.

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

Possible Exceptions

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

Possible Exceptions

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

Shopify Plugin ¶

Overview ¶

Click supports integration with Shopify. This section describes how to configure this plugin.

Set Up Integration ¶

Before you start: You need to have an active Shopify store to be able to access the integration plugin.

1. Access the Click Shopify plugin.
   
   

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

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

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

5. The section will expand. Enter the following fields:

Use test mode Check this option to integrate to a Click test (demo) account. By using a Click demo account, you can test your integration without moving any real money. All transactions will be passed through the Click payment simulator. Uncheck this to integrate to a Click production account.

ClientID:AccountID You can find the Client ID and Account ID in your Merchant activation email. Note: If you are using test mode, use the “Test Merchant Activation” email. If you are integrating to Production, use the “Production Merchant Activation” email. Be careful to enter information into the ClientID:AccountID field in the correct format, for example, 123456:987654.

Secret Hash Key You can find the Secret Hash Key in the Click Merchant Portal. Go to “Web Payments”, and then “Integration Settings”. You will see the Secret Hash Key listed under the “Secret Hash Key” section. Log in to the portal using the Username and Password credentials shown in the upper section of the activation email. To access the Merchant Portal, go to https://client.paymarkclick.co.nz/ (or for a test account, https://clientuat.paymarkclick.co.nz/). Notes: This is not the API Password (shown separately in the Merchant Portal). If you are using test mode, use the “Test Merchant Activation” email. If you are integrating to Production, use the “Production Merchant Activation” email.

Payment methods It is important to only select those you have loaded with Worldline. If you attempt a transaction with another payment method your Customer will see an error. To check what is loaded you can contact Worldline on 0800 PAYMARK.

Shopify payments settings page:

Activation email:

Merchant Portal:

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

8. You will now see the checkout process with Click as a payment option. After completing the order, your customers can pay using the Click hosted payment page.

Magento Plugin ¶

Overview ¶

Paymark offers a free Magento plugin allowing you to take payments from a Magento 2.3 or 2.4 store via a Click Hosted Payment Page. You can see a demo website using the Click Magento plugin at https://paymark.onfiredigital.co.nz/.

Set Up Click account ¶

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

Install Magento plugin ¶

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

composer require paymark/click

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

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

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

#run magento setup
php bin/magento setup:upgrade

Configure Magento plugin ¶

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

The configuration options are as follows:

• Title: Title that will appear on the checkout page

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

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

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

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

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

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

Go live ¶

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

You’re now ready to accept payments online.

Reporting Service ¶

Overview ¶

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

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

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

Method Options ¶

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

Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request.

If an error occurs, or if invalid data is submitted, a response is provided to the requester in the form of a URL that includes an error code and a description (where applicable).

Input

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:

Result Options

Possible Errors and Exceptions

Marketing Token ¶

Overview ¶

A marketing token can be created for the purpose of tracking all transactions made with a particular card, for example, for loyalty purposes. Transactions done through an EFTPOS terminal or online through Paymark Click can be tracked, providing an omnichannel facility for Merchants. Marketing tokens are supported for Click transactions through the Paymark Hosted Standard Payment, Direct Post and Merchant Hosted Transaction Processing integration options. Note: Currently you cannot create a marketing token for Online EFTPOS transactions.

A marketing token differs to a payment token or card token, which are created for the purpose of processing financial transactions. Unlike payment or card tokens, marketing tokens are not limited to standard card types (Visa, MasterCard, American Express and Q Card cards). A marketing token can also be created for an EFTPOS card to track all transactions made with that card via EFTPOS terminals.

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

End Points ¶

For Standard Payment and Direct Post Click integrations, registration of a marketing token shares the same endpoints as Web Payments and is accessible at the below URLs:

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

Non-Production: https://uat.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest

For Merchant Hosted Transaction Processing, registration of a marketing token uses the following end points:

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

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

Retrieval and removal of a marketing token (for all integration options) uses the following end points:

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

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

Signing Up For The Marketing Token Service ¶

This service is not offered as a standard Paymark Click feature. To sign up to use this facility, please contact Paymark on click@paymark.co.nz.

How Marketing Tokens Work ¶

Standard Payment: When your web application registers a marketing token request, the Merchant Token service will return a unique URL that the Merchant application can use to load a secure Paymark Click page to register the marketing token. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Standard Payment service also offers the option to register a marketing token while processing a payment transaction. The “merchant_token” field in the Standard Payment request registers a marketing token and returns a marketing token identifier in the response.

Direct Post: When your web application registers a marketing token request, the Merchant Token service will return a Direct Post URL to which the marketing token details can be posted. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Direct Post service also offers the option to register a marketing token while processing a payment transaction. The “merchant_token” field in the Direct Post request registers a marketing token and returns a marketing token identifier in the response.

Merchant Hosted Transaction Processing: With this option, Merchants are able to utilise their own functions and processes to collect and store card details, and then make a direct server to server API call to register the marketing token via the Paymark Transaction Processing API. For standard cards, that is, Visa, MasterCard, American Express and Q Card, the Merchant Hosted Transaction Processing service also offers the option to register a marketing token while processing a payment transaction. The “merchantToken” field in the Merchant Hosted Transaction Processing request registers a marketing token and returns a marketing token identifier in the response.

Standard Payment Marketing Token Registration ¶

Transaction Flow

For all cards, a marketing token can be registered using the Standard Payment request integration with the following flow.

When registering a marketing token using the Standard Payment request integration, the Click Web Payments API supports only the Post to Return URL return option. The return option determines what happens after a transaction is completed. See also Two Return Options.

The marketing token will be posted back to the Merchant’s return URL. At the same time, the Cardholder will be redirected back to the return URL. Note: Your return_url must have a valid SSL certificate to avoid the Cardholder’s browser prompting any security warning messages.

For information on registering a marketing token at the same time as the payment is done, see Paymark Hosted Standard Payment.

Marketing Token Registration Request Data

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

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

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

Direct Post Marketing Token Registration ¶

Transaction Flow

For all cards, a marketing token can be registered using the Direct Post integration with the following flow.

For information on registering a marketing token at the same time as the payment is done, see Direct Post.

Marketing Token Registration Request Data

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

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

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

IVR Payments ¶

Introduction ¶

Paymark Click can take payments and store cards for later use via an Interactive Voice Response (IVR) that is integrated to your own IVR or telephony platform. The Click IVR is not yet available for Online EFTPOS payments.

The Click IVR is offered as a bespoke implementation. Should you wish to integrate with the Click IVR, please contact Paymark on click@paymark.co.nz to discuss options.

How the Click IVR Works ¶

There are three stages to an IVR transaction:

1. Transaction Registration: Merchant system registers a transaction request with Click IVR.
2. Transaction Processing: Paymark Click IVR collects card information and processes the transaction.
3. Status Retrieval: Merchant system retrieves transaction status.

These stages are shown in the diagram below.

End Points ¶

The Paymark Click IVR end points are accessible via the URLs below:

Production: https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/[MethodName]

Non-Production: https://uat.paymarkclick.co.nz/api/ivrpayments/registrar/rest/[MethodName]

HTTP Headers ¶

In addition to the headers that are required by the HTTP protocol, Paymark requires that you specify the Accept header. The Accept header is used to specify the content type that your client will accept.

The following header is required for all REST API calls to the Click IVR:

Accept: application/xml

IVR Transaction Registration ¶

The Paymark Click IVR Transaction Register method allows a Merchant system to register a transaction request with the Paymark Click IVR, and obtain a unique Registration ID for further transaction processing or retrieval of a transaction status.

Method name: register

This method receives transaction registration data. Data should be sent as a POST web request. All data should be provided in the body of the request.

Once the request is received, the input will be validated. If successful, a Registration ID will be returned. This Registration ID is then used to process the transaction and to retrieve the transaction status. If an error occurs or if invalid data is submitted, a response is provided to the requester in the form of XML message that includes an error code and a description (where applicable).

Request Data

The following table shows the input fields that can be posted to the Paymark Click IVR. These must be posted in the order shown in the table (alphabetical order). A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Example:

POST https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/register HTTP/1.1

Accept: application/xml

<RegisterIvrPaymentRequest xmlns="https://secure.paymarkclick.co.nz/api/">
     <AccountId>700152</AccountId>
     <AllowStoreCardOption>1</AllowStoreCardOption>
     <Amount>5.23</Amount>
     <HasStoredCard>0</HasStoredCard>
     <NotificationUrl>https://merchanthost/ivr/</NotificationUrl>
     <Particular>Particular</Particular>
     <Password>Paymark123</Password>
     <Reference>Reference</Reference>
     <ReturnPhoneNumber>091234567</ReturnPhoneNumber>
     <TokenReference>MerchantTokenRef</TokenReference>
     <Type>authorisation</Type>
     <Username>90127</Username>
</RegisterIvrPaymentRequest>

Request Result

On success, the Registration ID will be returned as a string in XML format.

Example:

<RegisterIvrPaymentResponse xmlns="https://secure.paymarkclick.co.nz/api/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <RegistrationId>100016</RegistrationId>
</RegisterIvrPaymentResponse>

IVR Transaction Processing ¶

Once a transaction request has successfully been registered, the Merchant system should then transfer the call to the Paymark Click IVR to collect and process card information.

Request Data

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

Request Result

IVR Transaction Status Retrieval ¶

Once a transaction has been processed, the Merchant system can retrieve the transaction status using the Registration ID. The method below should be used to retrieve the transaction status. Note: Authentication is achieved by passing an encoded username and password in the HTTP header in the incoming request. See also Authentication information in Overview section.

Method Name: getstatus

Request Data

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

Example:

GET https://secure.paymarkclick.co.nz/api/ivrpayments/registrar/rest/getstatus?
accountId=700152&
registrationId=100016
HTTP/1.1

Accept: application/xml

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Request Result

Output Fields

Voice Prompt Files ¶

The voice prompt files used in the IVR announcements can be either a .wav or .gsm file. Maximum file size is 15 KB. Files need to be sent to your integration contact person.

Merchant Web Site Requirements ¶

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

In addition, for Merchants that support Online EFTPOS payments, these acceptance mark guidelines apply.

General Requirements ¶

The Merchant’s web site needs to be secured using a SSL certificate.

There is no initial requirement for the Merchant to have a CAPTCHA type real person authentication method; Paymark reserves the right to ask the Merchant to implement such a feature.

From 30 April 2018, Paymark will cease support for TLS 1.0 and 1.1. You must connect with TLS 1.2.

Branding Requirements ¶

A Paymark logo must always be displayed on the payment page. Please contact Paymark for logos and branding requirements.

Online EFTPOS Requirements ¶

If Online EFTPOS is enabled, the Merchant’s web site needs to provide information on Online EFTPOS with this payment method, for example, mouse over help text. The copy for this is: “For help on installing and using your bank’s mobile app please visit their website.”.

The Online EFTPOS payerID must be validated for general correctness, for example, correct number of digits. Paymark will provide copy to display in the event the payerID has failed this validation.

Mobile number validation rules for all Consumer Banks are:

• Begins with 020 / 1 / 2 / 7 / 8 / 9 (zero two …).

• 023, 024, 025, 026 not allowed.

• Minimum 9 digits, maximum 11 digits.

• Only numeric characters allowed.

Examples (not exhaustive!):

Allowed:

• 021012345

• 0221234567

Not allowed:

• 021-012-345

• +64 22 123 4567

• 026123456

The Merchant may choose to add additional usability aids such as a drop down list of valid mobile prefixes.

In addition, for Co-operative Bank payments, Customer ID validation rules are:

• Exactly 7 digits

• Begins with 1 - 9

In addition, for Westpac payments, Westpac 1 ID validation rules are shown below.

There are two types of Westpac One IDs: both are sent to Click with the payerIdType “WESTPAC1ID”.

“Tele ID”: 4 - 9 digits long, can start with any number. “Self Selected ID”: 4 - 20 character string, minimum one letter, valid characters are letters: [A-Z a-z], numbers: [0-9], fullstop, underscore, dash, backslash: [ . _ - \ ].

Determining the Payer ID Type:

• If all numbers and meets the mobile number validation, payerIdType = “MOBILE”. Note: This includes 9 digit numbers starting with “02”. Else,

• If all numbers and NOT a mobile number (as above), must be a Tele ID, so validate as per Tele ID criteria above, and if valid, payerIdType = “WESTPAC1ID”.

• If at least 1 letter, must be a Self Selected ID, so validate as per Self Selected ID criteria above, and if valid, payerIdType = “WESTPAC1ID”.

For specific requirements on the presentation and handling of Online EFTPOS payments, please refer to the Online EFTPOS API specification or contact Paymark with any questions on click@paymark.co.nz.

REST Exceptions ¶

Overview ¶

This section details the API error codes and messages that may be seen in the Paymark Click APIs. In the event a REST Exception occurs, the transaction would be rejected by the API.

The table below contains the standard HTTP response codes and related service error number(s) for the REST methods.

The “error type” element will contain one of the following denoting the type of exception:

• AUTHENTICATION Occurred whilst authenticating the service consumer.

• PARAMETER Occurred whilst validating a parameter passed to the service.

• SERVICE Occurred while processing the request.

• UNSPECIFIED Occurred unexpectedly, contact Paymark.

Example:

401 Unauthorised

REST APIs Error Messages ¶

The REST APIs (including Merchant Hosted transaction processing) will return the error message in JSON format.

{
   "code": 3000,
   "message": "Authentication error. Username, AccountId and/or Password are incorrect"
}

Paymark Hosted Standard Payment and Direct Post Error Messages ¶

The Paymark Hosted standard payment API (Paymark Click hosted payment page) and Direct Post API will return the error message in XML format.

Standard payment response message XML example:

<error
xmlns="https://secure.paymarkclick.co.nz/api/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<errormessage>Authentication error. Username, AccountId and/or Password are incorrect</errormessage>
<errornumber>3000</errornumber>
<errortype>AUTHENTICATION</errortype>
</error>

IVR Error Messages ¶

The IVR API will return the error message in XML format.

IVR response message XML example:

<Error
xmlns="https://secure.paymarkclick.co.nz/api/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorMessage>Authentication error. Username, AccountId and/or Password are incorrect</ErrorMessage>
<ErrorNumber>3000</ErrorNumber>
<ErrorType>AUTHENTICATION</ErrorType>
</Error>

Payment Service Errors ¶

Transaction Response Codes and Messages ¶

Overview ¶

This section details the transaction responses and messages, including bank error codes, that may be seen in the Paymark Click APIs.

Transaction Responses and Error Messages ¶

Once a transaction is successfully submitted for processing, that is, no REST Exceptions have occurred, the transaction response returned will indicate the status of the transaction along with an error code and error message (if not successful).

Test Card Details ¶

Overview ¶

This section details the test cards that may be used in the Click non-production environment.

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

Card Numbers ¶

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

Online EFTPOS Sandbox ¶

Overview ¶

The Online EFTPOS Sandbox is part of the Paymark Click non-production environment.

The sandbox can be used to simulate Online EFTPOS payment and refund operations for each Consumer Bank (ASB, The Co-operative Bank, Heartland and Westpac). The transaction amount used in the payment or refund request will determine the response that is received.

ASB Transactions ¶

The following responses can be simulated for ASB transactions (bankId = ASB).

Payment Request ¶

Status updates for “consumer responses” are received approximately 10 seconds after the payment request has been sent; the status in the response to the initial request is SUBMITTED.

The terminal status will be received in the response to the initial request for all “system responses”.

Authorised Scenarios

Declined Scenarios