Linked Gateway API

Connections ¶

Transport ¶

The Linked Gateway API is a RESTful API over HTTP, with a JSON payload.

HTTP Headers ¶

In addition to the headers that are required by the HTTP protocol, Worldline NZ requires that you specify the User Agent, Accept and Authorization headers.

The User Agent header identifies the client software originating the request.

The Accept header is used to specify the content type that your client will accept. Linked Gateway uses application/vnd.paymark_api+json;version=2.0 as its content type. Any other requested content types will result in a 406 Not Acceptable response.

The Authorization header is used to authenticate and authorise requests to Linked Gateway.

Versioning ¶

The Accept header is used to define the requested version of a resource, as defined in the HTTP Headers section.

You should expect that the Linked Gateway API will evolve over time as Worldline NZ adds new features. To ensure compatibility, you must specify the API version with every call you make to the API. At the moment, the latest version is 3.0.

End Points ¶

The base URL for all Linked Gateway Production endpoints is https://api.paymark.nz/

The base URL for all Linked Gateway pre-Production (Sandbox) endpoints is https://apitest.paymark.nz/

Please email lg

The endpoints available are:

• /bearer for authenticating and obtaining OAuth 2.0 bearer tokens.

• /transaction/payment for payments.

• /transaction/refund for refunds.

• /transaction/status for status checks.

• /transaction/authorisation for authorisations.

• /transaction/capture for captures.

• /transaction/cancel for cancellations.

For example, the full URL for the Production payment endpoint is: https://api.paymark.nz/transaction/v3/payment.

For example, the full URL for the Sandbox payment endpoint is: https://apitest.paymark.nz/transaction/v3/payment.

Errors ¶

The HTTP status code in the response is used to communicate any problems with a request. For example, if the Authorization header were to be omitted then a 401 Unauthorized response would be sent.

Exception Handling ¶

When creating a resource, any non-response or 5xx HTTP errors should be treated as an exception.

Important Note: To ensure financial integrity, you should issue a GET to the appropriate endpoint to see if the transaction was created and its status.

Security ¶

Worldline NZ requires that all connections are encrypted with TLS; there are no unencrypted endpoints available.

Your client must properly validate the TLS trust chain to ensure that your connection to Worldline NZ is secure.

Worldline NZ supports TLS 1.2 only.

Authentication ¶

Linked Gateway uses the OAuth 2.0 client credentials flow for authentication. You need to register your app to get a Consumer Key and Consumer Secret. You must protect these credentials.

Payment ¶

Overview ¶

A payment represents a request for a transfer of funds from the Cardholder to the Merchant.

A Merchant must be enabled for payment to send payment requests. Linked Gateway will reject Payment requests if the Merchant has not been enabled for this transaction type by their Acquiring Bank.

Create Payment ¶

Creates a new payment for processing on the Worldline NZ’s network. The payment will be processed immediately and the returned resource will communicate whether the payment was approved or declined.

PAYMENT REQUEST

POST /transaction/payment

Provide a JSON formatted payment resource as per the examples below.

Example Request - Making an eCommerce Payment with Card Data

POST /transaction/payment HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card":{
        "cardNumber":"5123456789012346",
        "expiryDate":"2015-07",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant":{
        "cardAcceptorIdCode":"854321",
        "transactionReference":"Test Reference",
        "transactionInformation":"Test Info",
        "timeStamp":"2015-04-14T11:55:04Z"
    },
    "transaction":{
        "amount":5467,
        "source":"Web Site",
        "storedCredentials":"stored",
        "settlementDate":"2015-04-15",
        "frequency":"instalment"
    }
}

Example Request – Making a 3DS Payment

POST /transaction/payment HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card":{
        "cardNumber":"5123456789012346",
        "expiryDate":"2015-07",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant":{
        "cardAcceptorIdCode":"854321",
        "transactionReference":"Test Reference",
        "transactionInformation":"Test Info",
        "timeStamp":"2015-04-14T11:55:04Z"
    },
    "transaction":{
        "amount":5649,
        "source":"Web Site"
    },
    "3ds2": {
    "transactionId": "f5064c70-1556-472a-bde1-dd6b45d37be6",
    "eci": "05",
    "authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "authenticationStatus": "Y",
    "authenticationStatusReason": "01",
    }
}

Example Request - Making an eCommerce Payment with Scheme Token Data

IMPORTANT When sending SCHEME_TOKEN transaction type for Customer Initiated Transactions the values provided on the following card object fields are:

SCHEME TOKEN TRANSACTION REQUEST GUIDE

POST /transaction/payment HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card":{
        "type": "SCHEME_TOKEN",
        "cardNumber":"5123456789012346",
        "expiryDate":"2015-07",
        "eci": "01",
        "cryptogram": "AwAAAAAAPboI4MoAmZZRghEAAAA=",
        "cardSecurityCodePresence":"Present"

    },
    "merchant":{
        "cardAcceptorIdCode":"854321",
        "transactionReference":"Test Reference",
        "transactionInformation":"Test Info",
        "timeStamp":"2015-04-14T11:55:04Z"
    },
    "transaction":{
        "amount":5467,
        "source":"Web Site",
        "storedCredentials":"stored",
        "settlementDate":"2024-03-05",
        "frequency":"single"
    }
}

PAYMENT RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full payment resource as per the example below.

Example Response - Making an eCommerce Payment with Card Data

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
"links": [
    {
    "href":"https://apitest.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    "rel": "self"
    } 
  ],
  "id":"ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status":"complete",
  "creationTime":"2015-04-14T11:55:04.946Z",
  "modificationTime":"2015-04-14T11:55:04.946Z",
  "card": {
    "token":"4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-12",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"854321",
    "transactionReference":"Test Reference",
    "transactionInformation":"Test Info",
    "street":"123 The Avenue",
    "suburb":"Auckland Heights",
    "city":"Auckland",
    "postalCode":"1000",
    "country":"NZ",
    "cardAcceptorName":"Greatest BBQ On Earth",
    "acquiringInstitutionId":"503513",
    "mcc":"1234",
    "terminal":"98765432101",
    "timeStamp":"2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount":5467,
    "currency":"NZD",
    "source":"Web Site ",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-04-15",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber":"061610",
    "storedCredentials":"stored",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Example Response – Making a 3DS Payment

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/payment/4ae27040-1cf7-476f-9537-6089cc1012d",
    "rel": "self"
    }
  ],
  "id":"4ae27040-1cf7-476f-9537-6089cc1012d",
  "status":"complete",
  "creationTime":"2015-04-14T11:55:04Z",
  "modificationTime":"2015-04-14T11:55:04Z",
  "card": {
    // Fields as per previous example
  },
  "merchant": {
    // Fields as per previous example
  },
  "transaction": {
    // Fields as per previous example
  },
  "3ds2": {
    "transactionId": "f5064c70-1556-472a-bde1-dd6b45d37be6",
    "eci": "05",
    "authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "authenticationStatus": "Y",
    "authenticationStatusReason": "01",
    "protocolVersion": "2.1.0"
 }
}

Example Response - Making a Scheme Token Payment

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": { 
    "maskedNumber": "512345..0008",
    "expiryDate": "2025-06", 
    "cardSecurityCodePresence": "Present", 
    "cardSecurityCodeResponse": "Not Processed"
    "type": "SCHEME_TOKEN"
  },
  "merchant": {
// Fields as per previous example
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "single",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "new",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Payment ¶

Reads a previously created payment. This does not change the payment in any way.

A payment can be read as soon as it has been created even if processing has not yet completed.

A payment can be read if it was created within the past 2 years. Payments performed more than 2 years ago will be archived by Worldline NZ.

READ PAYMENT REQUEST

To request a single payment resource:

GET /transaction/payment/{id}

Example Request - Single Payment

GET /transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

READ PAYMENT RESPONSE

If successful, returns HTTP 200 OK with the response body containing a payment resource.

Example Response – Single Payment Resource

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    "rel": "self"
    } 
  ],
  "id":"ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status":"complete",
  "creationTime":"2015-04-14T11:55:04.946Z",
  "modificationTime":"2015-04-14T11:55:04.946Z",
  "card": {
    "token":"4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-12",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"854321",
    "transactionReference":"Test Reference",
    "transactionInformation":"Test Info",
    "street":"123 The Avenue",
    "suburb":"Auckland Heights",
    "city":"Auckland",
    "postalCode":"1000",
    "country":"NZ",
    "cardAcceptorName":"Greatest BBQ On Earth",
    "acquiringInstitutionId":"503513",
    "mcc":"1234",
    "terminal":"98765432101",
    "timeStamp":"2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount":5467,
    "currency":"NZD",
    "source":"Web Site ",
    "frequency":"instalment",
    "processorResponseCode":"00",
    "settlementDate":"2015-04-15",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber":"061610",
    "storedCredentials":"stored",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Payments ¶

Reads a range of previously created payments. This does not change the payments in any way.

A payment can be read as soon as it has been created even if processing has not yet completed.

A payment can be read if it was created within the past 2 years. Payments performed more than 2 years ago will be archived by Worldline NZ.

QUERY PAYMENT REQUEST

To request a range of payment resources:

GET /transaction/payment?cardAcceptorIdCode={cardAcceptorIdCode}&status={status}&startTime={startTime}&endTime={endTime}

Example Request

GET /transaction/payment?cardAcceptorIdCode=854321&transactionReference="Test%20Reference" HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

QUERY PAYMENT RESPONSE

If successful, returns HTTP 200 OK with an array of zero or more payment resources that match the provided query in the response body.

Example Response – Array of Payments

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/payment?cardAcceptorIdCode=854321&transactionReference=Test%20Reference",
    "rel": "self"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    "rel": "ec2b8e9d-2b88-4460-9257-11d7a629b43b"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/payment/4ae27040-1cf7-476f-9537-6089cc1012d",
    "rel": "4ae27040-1cf7-476f-9537-6089cc1012d"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/payment/7c018008-624b-4436-b393-dc3ad1b22d1e",
    "rel": "7c018008-624b-4436-b393-dc3ad1b22d1e"
    }
  ],
  "payments": [ 
    {
    "id":"ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    // remaining fields as per create payment response
    }, 
    {
    "id":"4ae27040-1cf7-476f-9537-6089cc1012d",
    // remaining fields as per create payment response
    }, 
    {
    "id":"7c018008-624b-4436-b393-dc3ad1b22d1e",
    // remaining fields as per create payment response
    }
  ]
}

Payment Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card":{
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardSecurityCodePresence": "['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCode":"ABCD",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"
    },
    "merchant":{
        "cardAcceptorIdCode":"Worldline NZ assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction":{
        "systemTraceAuditNumber":"123456789012",
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring'|'instalment']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"12",
        "retrievalReferenceNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "identifierType":"<'Visa Checkout'|'Masterpass'>",
        "identifier":"XXXXXXXXXXXXXXX",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Payment ¶

Refer to Field Glossary section for field information.

Refund ¶

Overview ¶

A refund represents a request for a transfer of funds from a Merchant to a Cardholder. A refund may be standalone or may be linked to a previous payment or capture.

A Merchant must be enabled for refund to send refund requests. Linked Gateway 2.0 will reject refund requests if the Merchant has not been enabled for this transaction type by their Acquiring Bank.

Notes:

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

• It is the client’s responsibility to ensure the refund amount does not exceed the original payment amount.

• If explicity passing a reference for the capture request, the response will return the previous payment or previous capture reference

• scheme tokenisation standalone refund request is currently not implemented

• Refer to the table below when refunding a previous payment or previous capture

Create Refund ¶

Creates a new refund for processing on the Paymark network. The refund will be processed immediately and the returned resource will communicate whether the refund was approved or declined.

REFUND REQUEST

POST /transaction/refund

Provide a JSON formatted refund resource as per the examples below.

Example Request – Standalone Refund with Card Details

POST /transaction/refund HTTP/1.1

Authorization: Bearer Dypntpo33Qmir6jqCARrO36BVFmM

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "card": {
    "cardNumber":"5123456789012346",
    "expiryDate":"2020-12"
  },
  "merchant": {
    "cardAcceptorIdCode":"854321",
    "transactionReference":"test reference",
    "transactionInformation":"test information",
    "timeStamp":"2015-06-10T02:34:24.841Z"
  },
  "transaction": {
    "amount":5467,
    "source":"Web Site",
    "settlementDate":"2015-06-11"
  }
}

Example Request – Full Refund Linked to Prior Payment

Creating a refund for the full amount of a prior payment, where the ID of the prior payment is ec2b8e9d-2b88-4460-9257-11d7a629b43b and the payment was for $50. Note: The refund amount should not exceed the original payment amount.

POST /transaction/refund HTTP/1.1

Authorization: Bearer Dypntpo33Qmir6jqCARrO36BVFmM

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "paymentId": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    "transaction": {
      "amount": 5000
    }
}

Example Request – Partial Refund Linked to Prior Capture

Creating a refund for a portion ($20) of the amount of a prior payment ($54.67), where the ID of the prior payment is 8312422d-b42d-47f9-adf1-e468669d134b.

POST /transaction/refund HTTP/1.1

Authorization: Bearer Dypntpo33Qmir6jqCARrO36BVFmM

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "captureId": "8312422d-b42d-47f9-adf1-e468669d134b",
    "transaction": {
      "amount": 2000
    }
}

REFUND RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full refund resource.

Example Response – Standalone Refund with Card Details

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
   {
    "href":"https://apitest.paymark.nz/transaction/refund/c04a47b2-bf35-4fcb-b1e9-ddaa11364cb",
    "rel": "self"
    }
  ],
  "id":"c04a47b2-bf35-4fcb-b1e9-ddaa11364cba",
  "status":"complete",
  "creationTime":"2015-06-10T02:38:39.021Z",
  "modificationTime":"2015-06-10T02:38:39.021Z",
  "card": {
    "token":"89d74cec-b9c4-43ce-a762-89b166609aa1",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-12",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"854321",
    "transactionReference":"test reference",
    "transactionInformation":"test information",
    "street":"123 The Avenue",
    "suburb":"Auckland Heights",
    "city":"Auckland",
    "postalCode":"1000",
    "country":"NZ",
    "cardAcceptorName":"Carls Carpentry Cooperative",
    "acquiringInstitutionId":"503513",
    "mcc":"1234",
    "terminal":"98765432101",
    "timeStamp":"2015-06-10T02:34:24.841Z"
  },
  "transaction": {
    "amount":5467,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-06-11",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456",
    "systemTraceAuditNumber":"123456",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Refund ¶

Reads a previously created refund. This does not change the refund in any way.

A refund can be read as soon as it has been created even if processing has not yet completed.

A refund can be read if it was created within the past 2 years. Refunds performed more than 2 years ago will be archived by Paymark.

READ REFUND REQUEST

To request a single refund resource:

GET /transaction/refund/{id}

Example Request - Single Refund

GET /transaction/refund/ec2b8e9d-2b88-4460-9257-11d7a629b43b HTTP/1.1

Authorization: Bearer Dypntpo33Qmir6jqCARrO36BVFmM

Accept: application/vnd.paymark_api+json;version=2.0

READ REFUND RESPONSE

If successful, returns HTTP 200 OK with the response body containing a refund resource.

Example Response – Single Refund Resource

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/refund/c04a47b2-bf35-4fcb-b1e9-ddaa11364cb",
    "rel": "self"
    }
  ],
  "id":"c04a47b2-bf35-4fcb-b1e9-ddaa11364cba",
  "status":"complete",
  "creationTime":"2015-06-10T02:38:39.021Z",
  "modificationTime":"2015-06-10T02:38:39.021Z",
  "card": {
    "token":"89d74cec-b9c4-43ce-a762-89b166609aa1",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-12",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"854321",
    "transactionReference":"test reference",
    "transactionInformation":"test information",
    "street":"123 The Avenue",
    "suburb":"Auckland Heights",
    "city":"Auckland",
    "postalCode":"1000",
    "country":"NZ",
    "cardAcceptorName":"Carls Carpentry Cooperative",
    "acquiringInstitutionId":"503513",
    "mcc":"1234",
    "terminal":"98765432101",
    "timeStamp":"2015-06-10T02:38:39.021Z"
  },
  "transaction": {
    "amount":5467,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-06-11",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456",
    "systemTraceAuditNumber":"123456",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Refunds ¶

Reads a range of previously created refunds. This does not change the refunds in any way.

A refund can be read as soon as it has been created even if processing has not yet completed.

A refund can be read if it was created within the past 2 years. Refunds performed more than 2 years ago will be archived by Paymark.

QUERY REFUND REQUEST

To request a range of refund resources:

GET /transaction/refund?cardAcceptorIdCode={cardAcceptorIdCode}&startTime={startTime}&endTime={endTime}&status={status}

Example Request

GET /transaction/refund/?cardAcceptorIdCode=854321&startTime=2015-05-13 HTTP/1.1

Authorization: Bearer Dypntpo33Qmir6jqCARrO36BVFmM

Accept: application/vnd.paymark_api+json;version=2.0

QUERY REFUND RESPONSE

If successful, returns HTTP 200 OK with the response body. The response body is the similar to that shown under Query Payments, with an array of zero or more refund resources that match the provided query.

Refund Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card":{
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardSecurityCodePresence": "['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCode":"ABCD",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"
    },
    "merchant":{
        "cardAcceptorIdCode":"Worldline NZ assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction":{
        "systemTraceAuditNumber":"123456789012",
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring'|'instalment']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"12",
        "retrievalReferenceNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "identifierType":"<'Visa Checkout'|'Masterpass'>",
        "identifier":"XXXXXXXXXXXXXXX",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Refund ¶

Refer to Field Glossary section for field information.

Status Check ¶

Overview ¶

A status check enables a Merchant to verify a card, without reserving any Cardholder funds. This is suitable when saving a card that will be used for charging at a later time.

A Merchant must be enabled for “authorisation” to send status check requests: the status check leverages the authorisation feature. Linked Gateway 2.0 will reject status check requests if the Merchant has not been enabled for the authorisation transaction type by their Acquiring Bank.

Notes:

• scheme tokenisation transaction request for Status Check is currently not implemented

Create Status Check ¶

Creates a new status check for processing on the Paymark network. The status check will be processed immediately and the returned resource will communicate whether the status check was successful.

STATUS CHECK REQUEST

POST /transaction/status

Provide a JSON formatted status check resource as per the example below.

Example Request – Creating a Status Check

POST /transaction/status HTTP/1.1

Authorization: Bearer YbB4QM4LdVpo1MZrSAP5sjJg3GGO

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card": {
        "cardNumber":"5123456789012346",
        "expiryDate":"2020-01",
        "cardHolderName":"Pam Ark",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant": {
        "cardAcceptorIdCode":"850525",
        "transactionReference":"status check reference",
        "transactionInformation":"status check information",
        "timeStamp":"2018-02-21T03:05:39.289Z"
    },
    "transaction": {
        "source":"Web Site",
        "storedCredentials":"new"
    }
}

STATUS CHECK RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full status check resource.

Example Response – Status Check

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/status/
            76a1c90c-54c9-4588-8930-4a9b29f0d81b",
     "rel":"self"
     }
  ],
  "id":"76a1c90c-54c9-4588-8930-4a9b29f0d81b",
  "status":"complete",
  "creationTime":"2018-02-21T03:05:39.367Z",
  "modificationTime":"2018-02-21T03:05:39.367Z"
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01",
    "cardHolderName":"Pam Ark",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"status check reference",
    "transactionInformation":"status check information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2018-02-21T03:05:39.289Z"
  },
  "transaction": {
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2018-02-21",
    "authorisationCode":"145430",
    "retrievalReferenceNumber":"457897624042",
    "systemTraceAuditNumber":"567351",
    "storedCredentials":"new",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Status Check ¶

Reads a previously created status check. This does not change the status check in any way.

A status check can be read as soon as it has been created even if processing has not yet completed.

A status check can be read if it was created within the past 2 years. Status checks performed more than 2 years ago will be archived by Paymark.

READ STATUS CHECK REQUEST

To request a single status check resource:

GET /transaction/status/{id}

Example Request - Single Status Check

GET /transaction/status/76a1c90c-54c9-4588-8930-4a9b29f0d81b HTTP/1.1

Authorization: Bearer YbB4QM4LdVpo1MZrSAP5sjJg3GGO

Accept: application/vnd.paymark_api+json;version=2.0

READ STATUS CHECK RESPONSE

If successful, returns HTTP 200 OK with the response body containing a status check resource.

Example Response – Single Status Check Resource

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/status/
            76a1c90c-54c9-4588-8930-4a9b29f0d81b",
     "rel":"self"
     }
  ],
  "id":"76a1c90c-54c9-4588-8930-4a9b29f0d81b",
  "status":"complete",
  "creationTime":"2018-02-21T03:05:39.367Z",
  "modificationTime":"2018-02-21T03:05:39.367Z"
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01",
    "cardHolderName":"Pam Ark",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"status check reference",
    "transactionInformation":"status check information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2018-02-21T03:05:39.289Z"
  },
  "transaction": {
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2018-02-21",
    "authorisationCode":"145430",
    "retrievalReferenceNumber":"457897624042",
    "systemTraceAuditNumber":"567351",
    "storedCredentials":"new",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Status Check ¶

Reads a range of previously created status checks. This does not change the status checks in any way.

A status check can be read as soon as it has been created even if processing has not yet completed.

A status check can be read if it was created within the past 2 years. Status checks performed more than 2 years ago will be archived by Paymark.

QUERY STATUS CHECK REQUEST

To request a range of status check resources:

GET /transaction/status?cardAcceptorIdCode={cardAcceptorIdCode}&status={status}&startTime={startTime}&endTime={endTime}&transactionReference={transactionReference}

Example Request

GET /transaction/status?cardAcceptorIdCode=850525&transactionReference="statusCheckReference" HTTP/1.1

Authorization: Bearer YbB4QM4LdVpo1MZrSAP5sjJg3GGO

Accept: application/vnd.paymark_api+json;version=2.0

QUERY STATUS CHECK RESPONSE

If successful, returns HTTP 200 OK with an array of zero or more status check resources that match the provided query in the response body.

Example Response – Array of Status Checks

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/status?cardAcceptorIdCode=850525&transactionReference=status%20check%20reference",
    "rel": "self"
    },
    {
    "href":"https://apitest.paymark.nz/transaction/status/76a1c90c-54c9-4588-8930-4a9b29f0d81b",
    "rel": "76a1c90c-54c9-4588-8930-4a9b29f0d81b"
    },
    {
    "href":"https://apitest.paymark.nz/transaction/status/8b61c137-2a72-42cd-87c5-4a9f021955ba",
    "rel": "8b61c137-2a72-42cd-87c5-4a9f021955ba"
    }
  ],
  "statuses": [
    {
    "id":"76a1c90c-54c9-4588-8930-4a9b29f0d81b",
    \\ remaining fields as per create status check response
    },
    {
    "id":"8b61c137-2a72-42cd-87c5-4a9f021955ba",
    \\ remaining fields in line with create status check response
    }
    ]
}

Status Check Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card": {
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardHolderName":"Joe Bloggs",
        "cardSecurityCodePresence": "['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCode":"XXXX",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'| 'No keys, not certified or both']"
    },
    "merchant": {
        "cardAcceptorIdCode":"Paymark assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction": {
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",  
        "storedCredentials":"['new'|'stored']",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Status Check ¶

Refer to Field Glossary section for field information.

Authorisation ¶

Overview ¶

An authorisation represents a request for a pre-allocation of Cardholder funds to a Merchant but does not result in a transfer of funds unless one or more captures is created to transfer the pre-allocated funds. If the authorised amount is not captured, the pre-allocated funds will expire.

A Merchant must be enabled for authorisation to send authorisation requests. Linked Gateway will reject authorisation requests if the Merchant has not been enabled for this transaction type by their Acquiring Bank.

Create Authorisation ¶

Creates a new authorisation for processing on the Worldline NZ’s network. The authorisation will be processed immediately and the returned resource will communicate whether the authorisation was approved or declined.

AUTHORISATION REQUEST

POST /transaction/authorisation

Provide a JSON formatted authorisation resource as per the examples below.

Example Request – Creating an Authorisation

POST /transaction/authorisation HTTP/1.1

Authorization: Bearer m2ZmqGOpXteDKXlIeCH1rpmLHg6F

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card": {
        "cardNumber":"5123456789012346",
        "expiryDate":"2020-01",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant": {
        "cardAcceptorIdCode":"850525",
        "transactionReference":"auth reference",
        "transactionInformation":"auth information",
        "timeStamp":"2015-05-26T03:05:00.289Z"
    },
    "transaction": {
        "amount":1000,
        "source":"Web Site"
        "periodType":"calendar days",
        "periodDuration":1,
        "storedCredentials":"new",
        "settlementDate":"2015-05-27"
    }
}

Example Request – Creating a 3DS Authorisation

POST /transaction/authorisation HTTP/1.1

Authorization: Bearer m2ZmqGOpXteDKXlIeCH1rpmLHg6F

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card": {
        "cardNumber":"5123450000000008",
        "expiryDate":"2039-01",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant": {
        "cardAcceptorIdCode":"850525",
        "transactionReference":"auth reference",
        "transactionInformation":"auth information",
        "timeStamp":"2015-05-26T03:05:00.289Z"
    },
    "transaction": {
        "amount":1000,
        "source":"Web Site"
        "periodType":"calendar days",
        "periodDuration":1
    },
    "3ds2": {
        "transactionId": "f5064c70-1556-472a-bde1-dd6b45d37be6",
        "eci": "05",
        "authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
        "authenticationStatus": "Y",
        "authenticationStatusReason": "01",
        "eci": "05"
  }
}

Example Request - Making an eCommerce Authorisation with Scheme Token Data

IMPORTANT When sending SCHEME_TOKEN transaction type for Customer Initiated Transactions the values provided on the following card object fields are:

SCHEME TOKEN TRANSACTION REQUEST GUIDE

POST /transaction/authorisation HTTP/1.1

Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "card":{
        "type": "SCHEME_TOKEN",
        "cardNumber":"5123456789012346",
        "expiryDate":"2015-07",
        "eci": "05",
        "cryptogram": "AwAAAAAAPboI4MoAmZZRghEAAAA=",
        "cardSecurityCodePresence":"Present"

    },
    "merchant":{
        "cardAcceptorIdCode":"854321",
        "transactionReference":"Test Reference",
        "transactionInformation":"Test Info",
        "timeStamp":"2015-04-14T11:55:04Z"
    },
    "transaction":{
        "amount":5467,
        "source":"Web Site",
        "storedCredentials":"new",
        "settlementDate":"2024-03-05",
        "frequency":"single"
    }
}

AUTHORISATION RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full authorisation resource.

Example Response – Authorisation

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/5296a82d-8b05-40a6-b33e-2038c8670b3a",
     "rel":"self"
     }
  ],
  "id":"5296a82d-8b05-40a6-b33e-2038c8670b3a",
  "status":"complete",
  "creationTime":"2015-05-26T03:14:39.367Z",
  "modificationTime":"2015-05-26T03:14:39.367Z"
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-26T03:05:00.289Z"
  },
  "transaction": {
    "amount":1000,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"120430",
    "retrievalReferenceNumber":"571997624040",
    "systemTraceAuditNumber":"110351",
    "periodType":"calendar days",
    "periodDuration":1,
    "storedCredentials":"new",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Example Response – 3DS Authorisation

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/8ca82611-0b78-40ba-94c0-80f3eb208459",
    "rel":"self"
    } 
  ],
  "id":"8ca82611-0b78-40ba-94c0-80f3eb208459",
  "status":"complete",
  "creationTime":"2015-05-26T03:14:39.367Z",
  "modificationTime":"2015-05-26T03:14:39.367Z"
  "card": {
    // fields as per previous example
  },
  "merchant": {
    // fields as per previous example
  },
  "transaction": {
    // fields as per previous example
  },
  "3ds2": {
    "transactionId": "f5064c70-1556-472a-bde1-dd6b45d37be6",
    "eci": "05",
    "authenticationValue": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
    "authenticationStatus": "Y",
    "authenticationStatusReason": "01",
    "protocolVersion": "2.1.0"
 }
}

Example Response – eCommerce Authorisation with Scheme Token Data

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/
            3f83d525-8f50-4261-839e-e56032e1b0d5",
    "rel":"self"
    }
  ],
  "id":"3f83d525-8f50-4261-839e-e56032e1b0d5",
  "status":"complete",
  "creationTime":"2015-05-26T03:14:39.367Z",
  "modificationTime":"2015-05-26T03:14:39.367Z"
  "card": { 
    "maskedNumber": "512345..0008",
    "expiryDate": "2025-06", 
    "cardSecurityCodePresence": "Present", 
    "cardSecurityCodeResponse": "Not Processed",
    "eci": "05",
    "type": "SCHEME_TOKEN"
  },
  "merchant": {
    [fields as per previous example]
  },
  "transaction": {
    "amount": 2000,
    "currency": "NZD",
    "frequency": "single",
    "source": "Web Site",
    "periodType": "calendar days",
    "periodDuration": "20",
    "settlementDate": "2024-03-27",
    "processorResponseCode": "00",
    "authorisationCode": "507960",
    "retrievalReferenceNumber": "408705071078",
    "systemTraceAuditNumber": "71078",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Example Response – Authorisation Approved for Some of the Amount Requested (“Partial Authorisation”)

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/f52d491e-28b1-4d92-bc11-8128caa0251d",
     "rel":"self"
     }
  ],
  "id":"f52d491e-28b1-4d92-bc11-8128caa0251d",
  "status":"complete",
  "creationTime":"2018-03-13T04:38:12.457Z",
  "modificationTime":"2018-03-13T04:38:12.457Z"
  "card": {
    [fields as per previous example]
  },
  "merchant": {
    [fields as per previous example]
  },
  "transaction": {
    "amount":800,
    "additionalAmount": {
         "originalAmount": "1000"
    },
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"10",
    "settlementDate":"2018-03-13",
    "authorisationCode":"457854",
    "retrievalReferenceNumber":"621997624040",
    "systemTraceAuditNumber":"110397",
    "periodType":"calendar days",
    "periodDuration":1,
    "storedCredentials":"stored",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Authorisation ¶

Reads a previously created authorisation. This does not change the authorisation in any way.

An authorisation can be read as soon as it has been created even if processing has not yet completed.

An authorisation can be read if it was created within the past 2 years. Authorisations performed more than 2 years ago will be archived by Worldline NZ.

READ AUTHORISATION REQUEST

To request a single authorisation resource:

GET /transaction/authorisation/{id}

Example Request - Single Authorisation

GET /transaction/authorisation/5296a82d-8b05-40a6-b33e-2038c8670b3a HTTP/1.1

Authorization: Bearer m2ZmqGOpXteDKXlIeCH1rpmLHg6F

Accept: application/vnd.paymark_api+json;version=2.0

READ AUTHORISATION RESPONSE

If successful, returns HTTP 200 OK with the response body containing an authorisation resource.

Example Response – Single Authorisation Resource

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
   {
    "href":"https://apitest.paymark.nz/transaction/authorisation/5296a82d-8b05-40a6-b33e-2038c8670b3a",
     "rel":"self"
    }
  ],
  "id":"5296a82d-8b05-40a6-b33e-2038c8670b3a",
  "status":"complete",
  "creationTime":"2015-05-26T03:14:39.367Z",
  "modificationTime":"2015-05-26T03:14:39.367Z"
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01",
    "cardSecurityCodePresence":"Present",
    "cardSecurityCodeResponse":"Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-26T03:05:00.289Z"
  },
  "transaction": {
    "amount":1000,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"120430",
    "retrievalReferenceNumber":"571997624040",
    "systemTraceAuditNumber":"110351",
    "periodType":"calendar days",
    "periodDuration":1,
    "storedCredentials":"new",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Authorisations ¶

Reads a range of previously created authorisations. This does not change the authorisations in any way.

An authorisation can be read as soon as it has been created even if processing has not yet completed.

An authorisation can be read if it was created within the past 2 years. Authorisations performed more than 2 years ago will be archived by Worldline NZ.

QUERY AUTHORISATION REQUEST

To request a range of authorisation resources:

GET /transaction/authorisation?cardAcceptorIdCode={cardAcceptorIdCode}&status={status}&startTime={startTime}&endTime={endTime}&transactionReference={transactionReference}

Example Request

GET /transaction/authorisation?cardAcceptorIdCode=850525&transactionReference="auth reference" HTTP/1.1

Authorization: Bearer m2ZmqGOpXteDKXlIeCH1rpmLHg6F

Accept: application/vnd.paymark_api+json;version=2.0

QUERY AUTHORISATION RESPONSE

If successful, returns HTTP 200 OK with an array of zero or more authorisation resources that match the provided query in the response body.

Example Response – Array of Authorisations

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation?cardAcceptorIdCode=850525&transactionReference=auth%20reference",
    "rel": "self"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/5296a82d-8b05-40a6-b33e-2038c8670b3a",
    "rel": "5296a82d-8b05-40a6-b33e-2038c8670b3a"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/8ca82611-0b78-40ba-94c0-80f3eb208459",
    "rel": "8ca82611-0b78-40ba-94c0-80f3eb208459"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/authorisation/3f83d525-8f50-4261-839e-e56032e1b0d5",
    "rel": "3f83d525-8f50-4261-839e-e56032e1b0d5"
    }
  ],
  "authorisations": [ 
    {
    "id":"5296a82d-8b05-40a6-b33e-2038c8670b3a",
    // remaining fields as per create authorisation response
    }, 
    {
    "id":"8ca82611-0b78-40ba-94c0-80f3eb208459",
    // remaining fields as per create authorisation response
    }, 
    {
    "id":"3f83d525-8f50-4261-839e-e56032e1b0d5",
    // remaining fields as per create authorisation response
    }
  ]
}

Authorisation Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card": {
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardSecurityCodePresence":"['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCode":"XXXX",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']"
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"      
    },
    "merchant": {
        "cardAcceptorIdCode":"Worldline NZ assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction": {
        "amount":12345,
        "additionalAmount": {
            "originalAmount": "22345"
        },
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",
        "periodType":"['minutes'|'hours'|'calendar days']",
        "periodDuration":"[1 to 99]",    
        "storedCredentials":"['new'|'stored']",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Authorisation ¶

Refer to Field Glossary section for field information.

Capture ¶

Overview ¶

A capture relates to a matching authorisation, resulting in a transfer of funds from the Cardholder to the Merchant.

A Merchant must be enabled for capture to send capture requests. Linked Gateway will reject capture requests if the Merchant has not been enabled for this transaction type by their Acquiring Bank.

Notes:

• All authorisations must have a corresponding capture(s) or cancellation transaction.

• If a capture is done, no cancellation is needed (or possible).

• If explicity passing a reference for the capture request, the response will return the reference used for prior authorisation

• Linked Gateway 2.0 does not enforce a limit on the total amount captured. The capture may be for the whole value of the authorisation, or for part of the value. It is the client’s responsibility to ensure the total of all captures against an authorisation is not greater than the original authorisation amount.

Create Capture ¶

Creates a new capture for processing on the Worldline NZ’s network. The capture must reference a previous authorisation, and the total amount of all captures created must be no more than the amount of the original authorisation.

The capture will be processed immediately and the returned resource will communicate whether the capture was approved or declined.

CAPTURE REQUEST

POST /transaction/capture

Provide a JSON formatted capture resource as per the examples below.

Example Request – Interim Capture for $8.00 (Authorisation was for $10.00)

POST /transaction/capture HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "authorisationId":"5296a82d-8b05-40a6-b33e-2038c8670b3a",
    "transaction": {
        "amount":800,
        "conditionIndicator":"Partial"
    }
}

Example Request – Final Capture for $2.00 (Authorisation was for $10.00)

POST /transaction/capture HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "authorisationId":"5296a82d-8b05-40a6-b33e-2038c8670b3a",
    "transaction": {
        "amount":200,
        "conditionIndicator":"Final",
        "settlementDate":"2015-05-28"
    }
}

CAPTURE RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full capture resource.

Example Response – Interim Capture for $8.00

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/capture/dfdf6f47-462e-442c-89b7-240e82166672",
    "rel":"self"
    }
  ],
  "id":"dfdf6f47-462e-442c-89b7-240e82166672",
  "status":"complete",
  "creationTime":"2015-05-27T01:27:03.763Z",
  "modificationTime":"2015-05-27T01:27:03.763Z",
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01" 
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-27T01:27:03.763Z"
  },
  "transaction": {
    "amount":800,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber": "061683",
    "conditionIndicator":"Partial",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Example Response – Final Capture for $2.00

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":" https://apitest.paymark.nz/transaction/capture/5c23d9bd-b4eb-416c-aa0b-ce8d3350e259",
    "rel":"self"
    }
  ],
  "id":"5c23d9bd-b4eb-416c-aa0b-ce8d3350e259",
  "status":"complete",
  "creationTime":"2015-05-27T04:27:03.763Z",
  "modificationTime":"2015-05-27T04:27:03.763Z",
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-27T04:27:03.763Z"
  },
  "transaction": {
    "amount":200,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-28",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber": "061683",
    "conditionIndicator":"Final",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Capture ¶

Reads a previously created capture. This does not change the capture in any way.

A capture can be read as soon as it has been created even if processing has not yet completed.

A capture can be read if it was created within the past 2 years. Captures performed more than 2 years ago will be archived by Worldline NZ.

READ CAPTURE REQUEST

To request a single capture resource:

GET /transaction/capture/{id}

Example Request - Single Capture

GET /transaction/capture/dfdf6f47-462e-442c-89b7-240e82166672 HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

READ CAPTURE RESPONSE

If successful, returns HTTP 200 OK with the response body containing a capture resource.

Example Response – Single Capture Resource

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
   {
    "href":" https://apitest.paymark.nz/transaction/capture/dfdf6f47-462e-442c-89b7-240e82166672",
    "rel":"self"
    }
  ],
  "id":"dfdf6f47-462e-442c-89b7-240e82166672",
  "status":"complete",
  "creationTime":"2015-05-27T01:27:03.763Z",
  "modificationTime":"2015-05-27T01:27:03.763Z",
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-27T01:27:03.763Z"
  },
  "transaction": {
    "amount":800,
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber": "061683",
    "conditionIndicator":"Partial",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Captures ¶

Reads a range of previously created captures. This does not change the captures in any way.

A capture can be read as soon as it has been created even if processing has not yet completed.

A capture can be read if it was created within the past 2 years. Captures performed more than 2 years ago will be archived by Worldline NZ.

QUERY CAPTURE REQUEST

To request a range of capture resources:

GET /transaction/capture?cardAcceptorIdCode={cardAcceptorIdCode}&startTime={startTime}&endTime={endTime}&status={status}&transactionReference={transactionReference}

Example Request

GET /transaction/capture?cardAcceptorIdCode=850525&transactionReference="auth%20reference" HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

QUERY CAPTURE RESPONSE

If successful, returns HTTP 200 OK with an array of zero or more capture resources that match the provided query in the response body.

Example Response – Array of Captures

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/capture?cardAcceptorIdCode=850525&transactionReference=auth%20reference",
    "rel": "self"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/capture/dfdf6f47-462e-442c-89b7-240e82166672",
    "rel": "dfdf6f47-462e-442c-89b7-240e82166672"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/capture/5c23d9bd-b4eb-416c-aa0b-ce8d3350e259",
    "rel": "5c23d9bd-b4eb-416c-aa0b-ce8d3350e259"
    }
  ],
  "captures": [ 
    {
    "id":"dfdf6f47-462e-442c-89b7-240e82166672",
    \\ remaining fields as per create capture response
    }, 
    {
    "id":"5c23d9bd-b4eb-416c-aa0b-ce8d3350e259",
    \\ remaining fields as per create capture response
    }
  ]
}

Capture Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card":{
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardSecurityCodePresence": "['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCode":"ABCD",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"
    },
    "merchant":{
        "cardAcceptorIdCode":"Worldline NZ assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction":{
        "systemTraceAuditNumber":"123456789012",
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring'|'instalment']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"12",
        "retrievalReferenceNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "identifierType":"<'Visa Checkout'|'Masterpass'>",
        "identifier":"XXXXXXXXXXXXXXX",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Capture ¶

Refer to Field Glossary section for field information.

Cancellation ¶

Overview ¶

A cancellation refers to the process of stopping a payment flow at different stages, either before funds are captured or before transactions are settled. Depending on the timing and context, cancellation can take several forms:

Cancellation of Authorisation ¶

• This refers to voiding an approved authorisation before any capture is attempted.

• It removes the hold on the cardholder’s funds.

• Once cancelled, no capture should be attempted against the original authorisation.

• When cancelling an authorisation, use the Authorisation ID.

Cancellation of Capture ¶

• This applies when a capture has already been performed, but before the funds have settled (i.e., before they’re transferred to the merchant).

• This cancels the captured amount from being settled.

• When cancelling a capture, use the Capture ID.

• If the capture has already settled, a refund must be initiated instead.

Cancellation of Payment ¶

• This refers to cancelling a payment.

• No settlement will occur.

• When cancelling a payment, use the Payment ID.

• If the payment has already settled, a refund must be initiated instead.

Notes:

• When the Merchant becomes aware an authorisation is no longer needed, the cancellation request should be done within 24 hours.

• If an authorisation request is not captured within the expiry period (set in the periodType and periodDuration fields of the matching authorisation), a cancellation request should be sent.

• While the client will see a cancellation “successful” response, until the Acquiring Bank has implemented this type of transaction, the authorisation will still be live and Cardholder funds continue to be held.

Cancellation Identifiers ¶

Environments ¶

Create Cancellation ¶

Creates a new cancellation for processing on the Worldline NZ’s network. The cancellation must reference a previous authorisation, capture or payment.

The cancellation will be processed immediately and the returned resource will communicate whether the cancellation was approved or declined.

CANCELLATION REQUEST

POST /transaction/cancel

Provide a JSON formatted cancellation resource as per the example below.

Example Request – Creating a Cancellation for Authorisation

POST /transaction/cancel HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "authorisationId":"5296a82d-8b05-40a6-b33e-2038c8670b3a"
}

CANCELLATION RESPONSE

If successful, returns HTTP 201 Created with the response body containing the full cancellation resource.

Example Response

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":"https://apitest.paymark.nz/transaction/cancel/c38c045b-bba4-44c9-95e6-6d24dbf45788",
    "rel":"self"
    }
  ],
  "id":"c38c045b-bba4-44c9-95e6-6d24dbf45788",
  "status":"complete",
  "creationTime":"2015-05-27T01:27:03.763Z",
  "modificationTime":"2015-05-27T01:27:03.763Z",
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-27T01:27:03.763Z"
  },
  "transaction": {
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber": "061683",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Read Cancellation ¶

Reads a previously created cancellation. This does not change the cancellation in any way. A cancellation can be read as soon as it has been created even if processing has not yet completed.

A cancellation can be read if it was created within the past 2 years. Cancellations performed more than 2 years ago will be archived by Worldline NZ.

READ CANCELLATION REQUEST

To request a single cancellation resource:

GET /transaction/cancel/{id}

Example Request - Single Cancellation

GET /transaction/cancel/c38c045b-bba4-44c9-95e6-6d24dbf45788 HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

READ CANCELLATION RESPONSE

If successful, returns HTTP 200 OK with the response body containing a cancellation resource.

Example Response – Single Cancellation Resource

HTTP/1.1 201 Created

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [
    {
    "href":" https://apitest.paymark.nz/transaction/cancel/c38c045b-bba4-44c9-95e6-6d24dbf45788",
    "rel":"self"
    }
  ],
  "id":"c38c045b-bba4-44c9-95e6-6d24dbf45788",
  "status":"complete",
  "creationTime":"2015-05-27T01:27:03.763Z",
  "modificationTime":"2015-05-27T01:27:03.763Z",
  "card": {
    "token":"1ac18c74-cead-4246-a56e-d87dee4b6866",
    "maskedNumber":"512345..2346",
    "expiryDate":"2020-01"
  },
  "merchant": {
    "cardAcceptorIdCode":"850525",
    "transactionReference":"auth reference",
    "transactionInformation":"auth information",
    "street":"5 The Parade",
    "suburb":"Christchurch Valley",
    "city":"Christchurch",
    "postalCode":"8000",
    "country":"NZ",
    "cardAcceptorName":"Saisais Sushi",
    "acquiringInstitutionId": "503513",
    "mcc":"1234",
    "terminal":"85052501",
    "timeStamp":"2015-05-27T01:27:03.763Z"
  },
  "transaction": {
    "currency":"NZD",
    "source":"Web Site",
    "frequency":"single",
    "processorResponseCode":"00",
    "settlementDate":"2015-05-27",
    "authorisationCode":"123456",
    "retrievalReferenceNumber":"123456789012",
    "systemTraceAuditNumber": "061683",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS",
    "merchantAdviceCode": "00"
  }
}

Query Cancellation ¶

Reads a range of previously created cancellations. This does not change the cancellations in any way.

A cancellation can be read as soon as it has been created even if processing has not yet completed.

A cancellation can be read if it was created within the past 2 years. Cancellations performed more than 2 years ago will be archived by Worldline NZ.

QUERY CANCELLATION REQUEST

To request a range of cancellation resources:

GET /transaction/cancel?cardAcceptorIdCode={cardAcceptorIdCode}&startTime={startTime}&endTime={endTime}&status={status}&transactionReference={transactionReference}

Example Request

GET /transaction/cancel?cardAcceptorIdCode=850525&transactionReference="auth%20reference" HTTP/1.1

Authorization: Bearer NmAdMXGQoGNqtM2go7LFeJZAEYhe

Accept: application/vnd.paymark_api+json;version=2.0

QUERY CANCELLATION RESPONSE

If successful, returns HTTP 200 OK with an array of zero or more cancellation resources that match the provided query in the response body.

Example Response - Array of Cancellations

HTTP/1.1 200 OK

Content-Type: application/vnd.paymark_api+json;version=2.0

{
  "links": [ 
    {
    "href":"https://apitest.paymark.nz/transaction/cancel?cardAcceptorIdCode=850525&transactionReference=cancel%20reference",
    "rel": "self"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/cancel/c38c045b-bba4-44c9-95e6-6d24dbf45788",
    "rel": "c38c045b-bba4-44c9-95e6-6d24dbf45788"
    }, 
    {
    "href":"https://apitest.paymark.nz/transaction/cancel/fbdf7cde-e2a3-4aa2-bdba-e7799fdef6f2",
    "rel": "fbdf7cde-e2a3-4aa2-bdba-e7799fdef6f2"
    }
  ],
  "cancellations": [ 
    {
    "id":"c38c045b-bba4-44c9-95e6-6d24dbf45788",
    \\ remaining fields as per create cancellation response
    }, 
    {
    "id":"fbdf7cde-e2a3-4aa2-bdba-e7799fdef6f2",
    \\ remaining fields as per create cancellation response
    }
  ]
}

Cancellation Resource Definition ¶

{
    "links":[
        {
        "href":"full URL in message",
        "rel":"self"
        }
    ],
    "id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "status":"['created'|'processing'|'complete'|'failed']",
    "creationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "modificationTime":"YYYY-MM-DDThh:mm:ss.000Z",
    "card": {
        "token":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "cardNumber":4111111111111111,
        "maskedNumber":"XXXXXX..XXXX",
        "expiryDate":"YYYY-MM",
        "cardSecurityCodePresence": "['Not Present'|'Present'|'Not Legible'|'Not Imprinted']",
        "cardSecurityCodeResponse": "['Match'|'No Match'|'Not Processed'|'Not on Card'| 'No keys, not certified or both']"
    },
    "authorisationId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "merchant": {
        "cardAcceptorIdCode":"Worldline NZ assigned merchant ID",
        "transactionReference":"my-unique-ref/01.1",
        "transactionInformation":"Informative Text.",
        "street":"merchant’s street address as provided by the bank ",
        "suburb":"merchant’s address suburb as provided by the bank",
        "city":"merchant’s address city as provided by the bank",
        "postalCode":"merchant’s address post code as provided by the bank",
        "country":"merchant’s address country as provided by the bank",
        "cardAcceptorName":"merchant’s trading name as provided by the bank",
        "acquiringInstitutionId":"merchant’s acquiring bank code",
        "mcc":"classification code as provided by the bank",
        "terminal":"XXXXXXXX",
        "timeStamp":"YYYY-MM-DDThh:mm:ss.000Z"
    },
    "transaction":{
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "gatewayRecommendation": "recommended action if transaction declines",
        "gatewayCode": "summary of the operation",
        "gatewayResult": "A system-generated high level overall result of the operation",
        "merchantAdviceCode": "Issuer generated response, acts as a signal for retry or abandonment"
    }
}

Required Fields for Cancellation ¶

Refer to Field Glossary section for field information.

// include(threeDomainSecure.apib)

Field Glossary ¶

General Fields ¶

card Object ¶

merchant Object ¶

transaction Object ¶

threedomainsecure object ¶

Note: None of these fields are permitted in conjunction with transaction.identifier and transaction.identifierType.

Test Card Details ¶

Overview ¶

This section details the test cards that may be used in the Linked Gateway 2.0 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 in Sandbox environment you must use one of the cards listed below.

Only use these cards to test for a specific integration. For any questions about your integration, please contact us at lgv2@paymark.co.nz

Error Messages ¶

Overview ¶

This section provides example error message responses and formats.

Validation Errors ¶

Generic 400 Error

{
    "error": "validation"
}

This could be returned in any of the following cases:

• The data passed in was not in correct format (i.e. JSON).

• Attempting to parse a field as the wrong type e.g. string field trying to be converted to an integer.

A message may be parsed in (passing the above checks) but may then fail on certain things such as:

• String too long.

• Incorrect format e.g. phone number containing letters.

If this is the case, the error response contains a bit more information to help the caller debug the situation:

{
    "error:": "validation",
    "messages": [
        {
            "field":"msisdn",
            "message":"Invalid format 'abc'"
        },
        {
            "field":"name"
            "message":"Field required"
        },
        {
            "field":"abc",
            "message":"unknown field"
        },
        {
            "field":"id",
             "message":"cannot update field"
         }
    ]
}

401 Unauthorized

No body.

403 Forbidden

No body.

404 Not Found

No body provided as client has all the information to deal with this response.

405 Method Not Allowed

{
    "error":"UnsupportedMediaType",
    "reference":"<uuid>"
}

409 Conflict Error

If the POSTing or the PUTing of an object will result in a state which conflicts with the web service.

Examples include:

• Creating a new record where one like it exists already e.g. “Phone number already registered”.

• Attempting to update an object that has changed since the client last retrieved it: refer to the dateModified field.

{
    "error:": "conflict",
    "messages": [
        {
            "field":"msisdn",
            "message":"msisdn 021987654 already registered"
        }
    ]
}

415 Unsupported Media Type

{
    "error":"UnsupportedMediaType",
    "reference":"<uuid>"
}

Server Error - 5XX ¶

Thrown when the server encounters an internal (or upstream) error and cannot recover.

A reference UUID is given back to the caller so that they can quote it back to Paymark if they would like some more information: Paymark logs the reference alongside the exception.

The transaction status should be queried with this UUID.

{
    "error":"Service Unavailable",
    "reference":"<uuid>"
}

Gateway Transaction Response ¶

Overview ¶

In Linked Gateway 2.0 (LG2.0), the response to a transaction includes a transaction object containing several fields that describe the outcome. These provide information from both the gateway and the downstream processor (e.g. issuer or acquirer).

Content-Type: application/vnd.paymark_api+json;version=2.0

{
    "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "single",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "new",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8",
    "gatewayRecommendation": "NO_ACTION",
    "gatewayCode": "APPROVED",
    "gatewayResult": "SUCCESS"
    }
}

Transaction Fields

Note: While processorResponseCode is the core field reflecting the raw response from the acquirer or issuer (and is typically used to determine success or decline), it should not be interpreted in isolation.

To fully understand a transaction outcome and determine the most appropriate next action, you should also evaluate the following additional fields returned in the transaction object:

• gatewayCode – The gateway’s classification of the result may align with or differ from processorResponseCode.

• gatewayResult – A high-level status of the transaction

• gatewayRecommendation – Advice from the gateway on how to proceed

• merchantAdviceCode – Optional field offering guidance based on scheme or issuer insights

Collectively, these fields provide a more accurate and actionable view of a transaction response. Relying on processorResponseCode alone may miss important retry or abandonment signals.

Gateway Code ¶

The table below shows possible gatewayCode values in Linked Gateway 2.0.

Table of Possible gatewayCode Values

Gateway Result ¶

Table of Possible gatewayResult Values

Gateway Recommendation ¶

Table of Possible gatewayRecommendation Values

Merchant Advice Code ¶

Note: Merchant Advice Code will be returned if supported by the banks

Processor Response Codes ¶

The table below shows responses that may occur in Linked Gateway 2.0 (LG2.0).

Revision History ¶