Click Batch Payment API

API Endpoint
https://api.paymark.nz

Introduction

The Batch Payment API allows a Merchant to submit a file of card token Purchase transactions for processing as a single batch, rather than sending each transaction individually.

A batch is submitted as a base64 encoded CSV file, validated on upload, then authorised for processing as a separate step. Results are retrieved as a second CSV file once processing has completed.

The API is available in the following environments.

Environment Endpoint
UAT https://apitest.uat.paymark.nz
Production https://api.paymark.nz

The endpoint paths in this section are relative to those base URLs.

Batch Processing must be enabled for your organisation before you can use this API. If it has not been enabled, requests will fail with a 500 Internal Server Error. Contact Click support to have your organisation enabled and to obtain your organisation ID.

A Swagger document for this API is also available here.

Specification

Each batch requires a unique batch name, which identifies the batch and ensures duplicate batches are not uploaded. This name is chosen by you and submitted both in the request body and in the batch file’s header row - the two must match exactly, or the request will be rejected.

Batch names are unique across all Click merchants, not just within your own organisation. Cuscal Paymark recommends prefixing your batch names with your organisation ID or a similar identifier to avoid collisions with other merchants.

The batch identifier must be unique, and the responsibility to ensure duplicate files are not uploaded lies with the submitter.

  • Batch CSV file structure:

    1. Header row of type HD
    2. One or more data rows of type DT
    3. Trailer row of type TR

  • Batch JSON payload encoding:

    1. Optionally compressed with gzip
    2. Encoded as base64

  • A batch may contain up to 30,000 transactions.

  • Only Purchase transactions are currently supported. Authorisation, Capture and Refund transaction types are not yet available through this API.

Authentication

Requests to this API require an OAuth bearer token, obtained using the bearer credentials configured in the Click Portal.

The token is passed in the Authorization header of every request:

Authorization: Bearer <access_token>

Every request body also includes a merchant object identifying your organisation.

Name Description Required Type Length
organisationId Your Click organisation ID. Required Number N/A

Create Bearer Token

POST https://api.paymark.nz/bearer/
Requestsexample 1
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Q29uc3VtZXJLZXk6Q29uc3VtZXJTZWNyZXQ=
Accept: application/json
Body
grant_type=client_credentials
Responses200
Headers
Content-Type: application/json
Body
{
  "issued_at": "1464126466974",
  "application_name": "111111-2c4e-42cc-b613-fe974111111a",
  "scope": "",
  "status": "approved",
  "expires_in": "3599",
  "token_type": "BearerToken",
  "client_id": "axxxxxxxxxxx",
  "access_token": "bxxxxxxx"
}

Create Bearer Token
POST/bearer/

Environment Endpoint
UAT https://apitest.uat.paymark.nz/bearer
Production https://api.paymark.nz/bearer

To use the Batch Payment API you must obtain a bearer token using the Consumer Key and Consumer Secret configured in the Click Portal. The bearer token returned must be provided in the Authorization header of all requests to the Batch Payment endpoints.

The bearer token has a limited lifetime. You will need to obtain a new token once it has expired.

The bearer token request header should contain authorisation that is Base64 encoded.

The format is ConsumerKey:ConsumerSecret

Batch Processing

Batch Create

POST https://api.paymark.nz/batch
Requestsexample 1
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
Body
{
  "merchant": {
    "organisationId": 123456
  },
  "batchName": "MERCHANT123-20260916-01",
  "transactionType": 1,
  "zipped": false,
  "fileLength": 482,
  "fileCRC32": 0,
  "base64TransactionFileData": "SEQsTUVSQ0hBTlQxMjMtMjAyNjA5MTYtMDEsRGFpbHkgcHVyY2hhc2Vz..."
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "resultSummary": 0,
  "resultMessage": "Success",
  "batchName": "MERCHANT123-20260916-01"
}
Headers
Content-Type: application/json
Body
{
  "resultSummary": 8,
  "resultMessage": "Batch Name Already Exists",
  "batchName": "MERCHANT123-20260916-01"
}

Create a batch
POST/batch

Uploads a batch file for validation. The batch is stored but not processed until it is authorised via Batch Execute.

Batch files are validated at the time of upload to ensure the format is valid and against applicable business rules, such as card numbers passing a Mod10 check and expiry dates being valid.

Invalid records are identified in real time. If more than 15% of records in the file are invalid, the whole file is rejected; correct the errors and resubmit. If less than 15% of records are invalid, the API continues to process the file and reports the results as normal in the result file - invalid records are marked as such and need to be corrected and resubmitted for processing.

Input Fields

Name Description Required Type Length
merchant Object identifying your organisation. See Authentication above. Required Object N/A
batchName The batch name. Must match the Batch Name in the file’s header row and be unique across all merchants. Required String 64
transactionType Transaction type to process. Only 1 (Purchase) is currently supported. Required Number N/A
zipped Whether the batch file is gzip compressed before base64 encoding. Required Boolean N/A
fileLength File length in bytes of the original batch file, before zip and base64 encoding. Required Number N/A
fileCRC32 CRC32 checksum of the original file, before zip and base64 encoding. Use 0 to skip this check. Required Number N/A
base64TransactionFileData The base64 encoded CSV file payload. See Batch File Format below. Required String N/A

Output Fields

Name Description Type Length
resultSummary Result status code. See table below. Number N/A
resultMessage Human readable description of the result. String N/A
batchName The batch name submitted in the request. String 64

Result Status Codes

Code Meaning
0 Accepted
3 File length check failed
4 File CRC32 check failed
5 File data checksum failed
6 Batch name not supplied
8 Batch name already exists
9 Bad record threshold exceeded (more than 15% of records invalid)
10 Batch exceeds the maximum of 30,000 transactions
99 Exception encountered. Covers validation failures not listed above, such as an invalid CSV value, a batch name mismatch between the request and the file header, or a transaction count mismatch in the trailer row. See resultMessage for details.

Batch File Format

The batch file contains a header row, followed by one or more data rows, followed by a trailer row. The first field in each row is the row type indicator.

Header Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to HD
Batch Name Alpha/Num(64) Unique batch name (supplied by you). Must match the batchName submitted in the request.
Batch File Descriptor Alpha/Num(64) Batch file description.

Data Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to DT
Account Number Numeric This value dictates which sub-account the transaction will be processed through.
Trn Type Enum Must be 1 (Credit Card - Purchase). No other transaction type is currently supported.
Click Token Numeric A previously generated card token.
Customer Number Alpha/Num(64) Reserved for future use. Not currently processed by the API.
Amount Numeric(19) Amount sent as dollars, e.g. 55.00
Receipt Alpha/Num(50) Reserved for future use (Capture and Refund transactions). Not currently processed by the API.
Particular Text(50) An additional reference that can be sent by you for reporting purposes. This field name can be changed to something more suitable to your business. Please advise Click if you wish to change it.
Reference Text(50) Merchant defined value stored with the transaction.
Frequency Number 1 = single, 2 = recurring, 3 = unscheduled, 4 = instalment
Agreement Id Alpha/Num(50) Identifies an agreement between the cardholder and the merchant. Required if the frequency is instalment, recurring or unscheduled. Must be empty if the frequency is single.

Trailer Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to TR
Total Transactions Numeric(19) Total number of transactions in the batch, excluding header and trailer. Must match the number of data rows.
Total Amount Numeric(19) Total value of all transactions in the batch. This field is used as a checksum only.

HTTP Status Codes

Status Returned when
200 OK resultSummary 0 (Accepted)
400 Bad Request any other resultSummary (3, 4, 5, 6, 8, 9, 10, 99). The same response body is returned, with the failure in resultSummary.
500 Internal Server Error Batch Processing is not enabled for your organisation, or an unhandled error occurred. The body is application/problem+json.

Batch Execute

POST https://api.paymark.nz/batch/execute
Requestsexample 1
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
Body
{
  "merchant": {
    "organisationId": 123456
  },
  "batchName": "MERCHANT123-20260916-01"
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "resultSummary": 0,
  "resultMessage": "OK",
  "batchName": "MERCHANT123-20260916-01"
}
Headers
Content-Type: application/json
Body
{
  "resultSummary": 3,
  "resultMessage": "Batch Invalid",
  "batchName": "MERCHANT123-20260916-99"
}

Execute a batch
POST/batch/execute

Authorises a previously submitted batch for processing. Until a batch is executed it remains pending and no transactions are sent for authorisation.

Input Fields

Name Description Required Type Length
merchant Object identifying your organisation. See Authentication above. Required Object N/A
batchName The batch name submitted in the original request. Required String 64

Output Fields

Name Description Type Length
resultSummary Result status code. See table below. Number N/A
resultMessage Human readable description of the result. String N/A
batchName The batch name submitted in the original request. String 64

Result Status Codes

Code Meaning
0 OK
3 Invalid batch name
4 Batch has already been cancelled
5 Batch has already been authorised
99 Exception encountered

HTTP Status Codes

Status Returned when
200 OK resultSummary 0 (OK) or 5 (Batch already Authorized)
400 Bad Request resultSummary 3 (Batch Invalid), 4 (Batch Complete) or 99 (Unhandled Exception).
500 Internal Server Error Batch Processing is not enabled for your organisation, or an unhandled error occurred. The body is application/problem+json.

Batch Cancel

POST https://api.paymark.nz/batch/cancel
Requestsexample 1
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
Body
{
  "merchant": {
    "organisationId": 123456
  },
  "batchName": "MERCHANT123-20260916-01"
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "resultSummary": 0,
  "resultMessage": "OK",
  "batchName": "MERCHANT123-20260916-01"
}
Headers
Content-Type: application/json
Body
{
  "resultSummary": 3,
  "resultMessage": "Batch Invalid",
  "batchName": "MERCHANT123-20260916-99"
}

Cancel a batch
POST/batch/cancel

Cancels a batch that has not yet completed processing. In-flight transactions will be completed; all remaining pending transactions will be marked as cancelled.

Cancelled transactions appear in the result file with error code 8000.

Input Fields

Name Description Required Type Length
merchant Object identifying your organisation. See Authentication above. Required Object N/A
batchName The batch name submitted in the original request. Required String 64

Output Fields

Name Description Type Length
resultSummary Result status code. See table below. Number N/A
resultMessage Human readable description of the result. String N/A
batchName The batch name submitted in the original request. String 64

Result Status Codes

Code Meaning
0 OK
3 Invalid batch name
4 Batch has already completed processing and cannot be cancelled
99 Exception encountered

HTTP Status Codes

Status Returned when
200 OK resultSummary 0 (OK) or 4 (Batch Complete)
400 Bad Request resultSummary 3 (Batch Invalid) or 99 (Unhandled Exception).
500 Internal Server Error Batch Processing is not enabled for your organisation, or an unhandled error occurred. The body is application/problem+json.

Batch Result

GET https://api.paymark.nz/batch/MERCHANT123-20260916-01/result?clientId=123456&zipped=false
Requestsexample 1
Headers
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
Responses200400
Headers
Content-Type: application/json
Body
{
  "batchStatus": 0,
  "fileLength": 812,
  "fileCRC32": 1479390729,
  "base64TransactionFileData": "SEQsTUVSQ0hBTlQxMjMtMjAyNjA5MTYtMDEN..."
}
Headers
Content-Type: application/json
Body
{
  "batchStatus": 3
}

Retrieve a batch result
GET/batch/{batchName}/result{?clientId,zipped}

Returns the result file for a completed batch. If the batch has not finished processing, the batchStatus field indicates its current state and no file is returned.

Output Fields

Name Description Type Length
batchStatus Batch status code. See table below. Number N/A
fileLength File length in bytes of the result file, before zip and base64 encoding. Present when batchStatus is 0. Number N/A
fileCRC32 CRC32 checksum of the result file, before zip and base64 encoding. Present when batchStatus is 0. Number N/A
base64TransactionFileData The base64 encoded result file. Present when batchStatus is 0. See Result File Format below. String N/A

Batch Status Codes

Code Meaning
0 OK
3 Invalid batch name
4 Batch has been cancelled
5 Batch is pending, waiting for authorisation
6 Batch is processing
99 Exception encountered

Result File Format

The result file contains a header row, followed by one or more data rows, followed by a trailer row. The first field in each row is the row type indicator.

Header Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to HD
Batch Name Alpha/Num(64) The batch name submitted in the original request.

Data Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to DT
Trn Type Numeric(1) Will always be 1 (Credit Card - Purchase).
Click Token Numeric The token supplied for this transaction in the original batch.
Result Numeric(1) 0 = Approved, 1 = Not approved
Error code Numeric(3) Blank if Result = 0. If Result = 1, the reason for the declined transaction as an error code. If the batch was cancelled via Batch Cancel, this will show 8000 for cancelled batch items.
Error description Alpha/Num(256) Blank if Result = 0. If Result = 1, the textual description of the error.
Amount Numeric(19) Amount sent as a dollar value, e.g. 55.00
Receipt Alpha/Num(50) Reserved for future use. Not currently populated.
Particular Text(50) The reference sent by you for reporting purposes.
Reference Text(50) Merchant defined value stored with the transaction.
Transaction Id Alpha/Num(50) Reference of the transaction in Click.

Trailer Row

Column Format Description
Row Type Alpha/Num(2) Must be equal to TR
Total Transactions Numeric(19) Total number of transactions in the batch, excluding header and trailer.
Total Amount Numeric(19) Total value of all transactions in the batch. This field is used as a checksum only.

Possible Exceptions

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

Status Returned when
200 OK batchStatus 0 (Ok), 5 (Batch is pending) or 6 (Batch is Processing)
400 Bad Request batchStatus 3 (Invalid batch number) or 99 (Exception encountered).
500 Internal Server Error Batch Processing is not enabled for your organisation, or an unhandled error occurred. The body is application/problem+json.
URI Parameters
HideShow
batchName
string (required) Example: MERCHANT123-20260916-01

The batch name submitted in the original request.

clientId
number (required) Example: 123456

Your Click organisation ID.

zipped
boolean (required) Example: false

Whether the returned result file should be gzip compressed before base64 encoding.

Generated by aglio on 29 Sep 2026