Cuscal Paymark eCommerce APIs

Build ¶

Choose an integration method ¶

Click offers four ways to integrate. All of them support cards (Visa, Mastercard and American Express), Apple Pay, Google Pay and Online EFTPOS.

The right choice is mostly a trade-off between how much of the payment experience you want to control and how much PCI-DSS compliance you are prepared to take on.

Hosted Payment Page

You send a payment request and receive a secure URL. Redirect the Customer to that URL and Cuscal Paymark hosts the payment page, collects the card or account details, processes the payment and returns the Customer to your site with the result.

Because the payment page is ours, your PCI-DSS compliance requirements are minimised. CSS customisation is supported so the page can carry your branding.

Custom Checkout

A JavaScript plugin renders payment fields directly on your own checkout page using iFrames, so the Customer is never redirected to our servers. You control the look, feel and flow of the payment experience.

Because the fields themselves are hosted by Cuscal Paymark, card details do not touch your servers and the PCI burden is lower than a full merchant hosted integration.

Batch API

Submit a file of previously tokenised card payments for processing as a single batch, instead of sending transactions one at a time. There is no payment page and the Cardholder is not present, so this suits scheduled or repeat billing rather than checkout.

The batch file carries payment tokens, not card numbers.

Merchant Hosted API

You collect the card details yourself and call our API server to server. This gives you complete control over the payment experience, and requires full PCI-DSS compliance because you are handling and storing card data.

Merchant Hosted must be approved by Cuscal Paymark before you integrate. You will also need to confirm with your acquirer that they will support a Merchant Hosted integration before you begin.

3D Secure

3D Secure is supported on Hosted Payment Page and Custom Checkout. Card payments can benefit from 3D Secure, more info here, as well as Cuscal Paymark’s merchant-managed fraud tools.

Build considerations ¶

End points

Each integration uses one of two domains. The individual endpoint paths are given in the relevant section of this documentation.

Token management and retrieve transaction endpoints sit on the same domain as the Merchant Hosted API.

HTTP headers

In addition to the headers required by the HTTP protocol, Cuscal Paymark requires that you specify the Content and Accept headers.

The Content header specifies the content type your application will pass in. The Accept header specifies the content type your client will accept.

The Hosted Payment Page API is stricter than the others: it requires exactly Content-Type: application/x-www-form-urlencoded and exactly Accept: application/xml. Any other value is rejected before the request is processed.

Authentication

Authentication differs by integration.

Token management and retrieve transaction use the same HTTP header method as the Merchant Hosted API.

Authentication in the request body

Used by the Hosted Payment Page API. Credentials are included in the transaction POST, in the username, password and account_id fields.

Note that the Hosted Payment Page API reads credentials only from the request body. An HTTP Basic Authorization header is ignored, and the request fails authentication as though the password were wrong.

Example:

username=90127&
password=Paymark123&
account_id=700152

Authentication in the HTTP header

Used by the Merchant Hosted API and the token management and retrieve transaction methods. An encoded username and password is passed in the HTTP header of the incoming request.

Format: username:password in base64 encoding.

Example:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Authentication with a bearer token

Used by Custom Checkout and the Batch API. Request an OAuth bearer token, then pass it in the Authorization header of every subsequent request.

Tokens are obtained from the bearer endpoint using the Consumer Key and Consumer Secret configured in the Click Portal, passed as base64 encoded ConsumerKey:ConsumerSecret. Bearer tokens have a limited lifetime and must be renewed once they expire.

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Compliance ¶

PCI ¶

Your PCI-DSS obligations depend on the integration method you choose, and on how much card data your systems touch. Keep the conversation about your PCI compliance going with your acquirer, as they are responsible for confirming your compliance status.

Cuscal Paymark’s PCI Attestation of Compliance is available on request. Contact us if you need a copy.

3D Secure ¶

3D Secure is available on the Hosted Payment Page and Custom Checkout integrations only. It is not available for Merchant Hosted or Batch API integrations.

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 also provides a level of chargeback protection for participating merchants under certain conditions.

If 3DS is enabled on your account, card scheme rules require you to send either the Cardholder’s email address or one of their phone numbers with every transaction.

The API will not reject a transaction that leaves these out, so it is easy to miss. Sending them gives the Issuer more to work with when deciding whether to challenge the Cardholder, which means more transactions complete without a challenge and fewer customers abandon the payment. The relevant fields are listed in the 3D Secure 2.1 guide.

Contact your acquirer for 3DS enrolment.

Card on File ¶

Card on File describes transactions where you have stored a Cardholder’s payment details and use them to process later payments, whether the Cardholder initiates the payment themselves or you initiate it on their behalf.

These transactions must be identified correctly using the transaction frequency and agreement fields. Doing so gives issuers a better understanding of the risk involved, which leads to higher authorisation approval rates and a better experience for your customers.

See the Card on File integration guide for the fields to send and how to handle cardholder-initiated and merchant-initiated transactions.

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:

• Purchase (Card, Apple Pay, Google Pay and Online EFTPOS) - money is taken from the customer’s account.

• Authorisation (card only) - money is held on the customer’s account but is not taken. Can be cancelled or captured.

• Status Check (card only) - checks that a card is valid and active, without holding or taking funds.

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

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

Transaction Flow for Hosted Payment Page

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

CSS customisation ¶

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

Once you have updated the CSS, you can upload this for approval via your Merchant Portal (Production portal, Demo portal). We will review the CSS and publish it in that environment. Note: To ensure replication across all Cuscal Paymark 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.

Batch Payments ¶

Click here to learn more about the Batch Payment API

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

Supports Online EFTPOS.

Does not support 3Dsecure.

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

Transaction Processing Outputs ¶

All of the transaction processing methods in this section have a standard set of response outputs as described below.

Output Fields

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

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.

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.

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.

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.

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

Payment Token ¶

Payment tokens represent a stored payment method and can be retrieved either by the token itself or by the merchant defined token reference.

Card Token ¶

Card tokens represent a stored card and can be retrieved, updated or removed by the token itself, or retrieved by the merchant defined token reference.

Magento Plugin ¶

Overview ¶

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

Set Up Cuscal Paymark 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 Cuscal Paymark account (You can find this in your merchant console after registering)

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

• Account ID: Cuscal Paymark 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 (Cuscal 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 Cuscal Paymark 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.

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. Cuscal Paymark reserves the right to ask the Merchant to implement CAPTCHA or a similar service.

Branding Requirements ¶

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

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