Linked Gateway API

Overview

Paymark Linked Gateway (LG) is our payment gateway that allows other gateways to connect and settle financial transactions with acquirers and card schemes.

This portal includes the information needed on how to integrate directly with LG APIs. For information on particular features, e.g. credential on file transactions or scheme token transactions, please see our Integration Guide.

LG supports the following transaction types:

  • Payment: charges the Customer’s card immediately and results in funds settled to the Merchant.

  • Refund: returns funds back to a Customer’s card and results in funds returned from the Merchant via the settlement process. Partial and full refunds are supported. Linked and standalone refunds are supported.

  • Status Check: validates Card details that a Customer has provided without reserving funds on the Card.

  • Authorisation: validates Card details that a Customer has provided and reserves funds on the Card for the Merchant. DOES NOT charge the Card and no funds are settled to the Merchant.

  • Capture: charges the Customer’s card using funds reserved from a prior authorisation, and results in funds settled to the Merchant.

  • Cancellation: removes a prior authorisation (and releases reserved funds on the Customer’s card) when these funds are no longer required.

For any assistance with this API specification, please contact Paymark on lgv2@paymark.co.nz.

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, Paymark 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 Paymark 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 2.0.

End Points

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

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

(UAT endpoint deprecated) -> https://lgapi.uat.paymark.nz/

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.

  • /transaction/payment-authentication for 3DS authentications.

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

For example, the full URL for the Sandbox payment endpoint is: https://apitest.paymark.nz/transaction/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

Paymark 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 Paymark is secure.

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

Obtain oAuth Bearer Token

POST https://api.paymark.nz//bearer
RequestsoAuth Bearer token
Headers
Content-Type: x-www-form-urlencoded
Authorization: Basic d21lOGNLVzV0eG9MNlp6TXZYZlVRWGlGa0tiSFc1WnE6aWtKNGlpSzhYdVpFMFhVcA==
Body
{
  "grant_type": "client_credentials"
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
  "issued_at": "1614133043705",
  "application_name": "896671b5-e6ee-42f8-a33b-df7fa240a54b",
  "scope": "",
  "status": "approved",
  "expires_in": "3599",
  "token_type": "BearerToken",
  "client_id": "eUU6UB7LeBzyazwzOEmDPajve1Mq4XgR",
  "access_token": "qtAGAWgkBL3rxBaVASwID7RC0KCN"
}

Obtain oAuth Bearer Token
POST/bearer

Before calling any Linked Gateway endpoint, you must obtain a Bearer token by issuing a POST to the /bearer endpoint, providing the Consumer Key and Consumer Secret as the username and password respectfully, using HTTP Basic authentication, and passing client_credentials as the grant_type.

The bearer token returned must be provided in the Authorization header of all requests to any other endpoints.

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


Payment

Overview

https://api.paymark.nz/transaction/payment

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.

Environment URL
Production https://api.paymark.nz/transaction/payment
Sandbox https://apitest.paymark.nz/transaction/payment

Create Payment

Creates a new payment for processing on the Paymark 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 – 3DS2

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:56:04Z"
    },
    "transaction":{
        "amount":5649,
        "source":"Web Site"
    },
    "3ds2": {
        "protocolVersion":"2.1.0",
        "transactionId":"5646a82d-8b05-40a6-b33e-2038c8670b3a",
        "authenticationStatus":"Y",
        "eci":"02",
        "authenticationStatusReason":"16",
        "authenticationValue":"AAABBQHLYDkkad8AImDLAAAAAAA="
    }
}

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:

Fields Value Description
cardNumber scheme token DPAN
expiryDate scheme token expiry date
eci scheme token eci value
cryptogram scheme token cryptogram

SCHEME TOKEN TRANSACTION REQUEST GUIDE

Fields Visa Mastercard AMEX
type Required Required Required
cryptogram Required Required -
eci Required Required Required
cardSecurityCode - - Required
expiryDate Required Required Required
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://lgapi.uat.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":"Mirandas Marvellous Muffins",
    "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"
  }
}

Example Response - 3DS2

HTTP/1.1 201 Created

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

{
    "links": [
        {
            "href":"https://lgapi.uat.paymark.nz/transaction/payment/7c018008-624b-4436-b393-dc3ad1b22d1e",
            "rel": "self"
        } 
    ],
    "id":"7c018008-624b-4436-b393-dc3ad1b22d1e",
    "status":"complete",
    "creationTime":"2015-04-14T11:56:04Z",
    "modificationTime":"2015-04-14T11:56:04Z",
    "card": {
        [fields as per previous example]
    },
    "merchant": {
        [fields as per previous example]
    },
    "transaction": {
        "amount":5649,
        "currency":"NZD",
        "source":"Web Site ",
        "frequency":"single",
        "processorResponseCode":"00",
        "settlementDate":"2015-04-14",
        "authorisationCode":"987654",
        "retrievalReferenceNumber":"987656789012",
        "systemTraceAuditNumber":"061610"
    },
    "3ds2": {
        "protocolVersion":"2.1.0",
        "transactionId":"5646a82d-8b05-40a6-b33e-2038c8670b3a",
        "authenticationStatus":"Y",
        "eci":"02",
        "authenticationStatusReason":"16",
        "authenticationValue":"AAABBQHLYDkkad8AImDLAAAAAAA=",
    }
}

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

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

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://lgapi.uat.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":"Mirandas Marvellous Muffins",
    "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"
  }
}

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

QUERY PAYMENT REQUEST

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of payment resource.
status string Status field of payment resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of payment resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of payment resource.
transactionReference string Merchant reference for a payment.

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 Reference" 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://lgapi.uat.paymark.nz/transaction/payment
     ?cardAcceptorIdCode=854321&transactionReference="Test Reference",
    "rel": "self"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/payment/
            ec2b8e9d-2b88-4460-9257-11d7a629b43b",
    "rel": "ec2b8e9d-2b88-4460-9257-11d7a629b43b"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/payment/
            4ae27040-1cf7-476f-9537-6089cc1012d",
    "rel": "4ae27040-1cf7-476f-9537-6089cc1012d"
    }, {
    "href":"https://lgapi.uat.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":"XXXX",
        "cardSecurityCodeResponse":"['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "paymentAccountReference":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"
    },
    "dsrp": {
        "tokenType":"['AETS'|'MDES'|'VTS'|'applePay'|'googlePay'|'samsungPay']",
        "tokenPan":"4111111111111111",
        "tokenExpiryDate":"YYYY-MM",
        "tokenSecurityCode":"XXXX",
        "eciIndicator":"XX",
        "cryptogram":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "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":{
        "systemTraceAuditNumber":"123456789012",
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre'|'Merchant']",
        "frequency":"['single'|'recurring'|'unscheduled']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"12",
        "retrievalReferenceNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "agreementId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    },
    "3ds2": {
        "protocolVersion":"X.X.X",
        "transactionId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "authenticationStatus":"X",
        "eci":"XX",
        "authenticationStatusReason":"XX",
        "authenticationValue":"XXXXXXXXXXXXXXXXXXXXXXXXXXX="
    }
}

Required Fields for Payment

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
card.cardNumber POST Yes
card.expiryDate POST Yes if transaction.frequency is “single”, or if transaction.frequency is “recurring” and it is the first “recurring” transaction for that card.
card.cardSecurityCodePresence POST Yes
card.cardSecurityCode POST Yes if cardSecurityCodePresence is “Present”.
card.type POST Yes if transaction is “SCHEME_TOKEN”
card.cryptogram POST Yes if transaction is “SCHEME_TOKEN”, Customer Initiated Transaction and Visa or Mastercard
card.eci POST Yes if transaction is “SCHEME_TOKEN”, Customer Initiated Transaction and Visa or Mastercard
merchant.cardAcceptorIdCode POST, GET Yes
merchant.transactionReference POST, GET Optional.
merchant.transactionInformation POST Optional.
merchant.timeStamp POST Optional.
transaction.amount POST Yes
transaction.source POST Optional, uses account default if not present.
transaction.frequency POST Optional, uses account default if not present.
Set to “single” for one-off payments or when charging a saved card e.g. the Customer has previously opted to save their Card then chooses to use this for a later purchase.
Set to “recurring” for a Merchant initiated payment where there is an agreement between a Cardholder and a Merchant to bill the Cardholder’s account on a periodic basis without a specified end date e.g. bill payment or subscription.
Set to “instalment” for a Merchant initiated payment where there is an agreement between a Cardholder and a Merchant to bill the Cardholder’s account where the number of payments is limited e.g. a purchase split over multiple payments.
transaction.storedCredentials POST Should always be provided for a transaction using a saved (tokenised) card.
transaction.agreementId POST Required if transaction.frequency is not “single”
transaction.settlementDate POST Optional.
3ds2.transactionId POST Refer to 3DS section.
3ds2.eci POST Refer to 3DS section.
3ds2.authenticationValue POST Refer to 3DS section.
3ds2.protocolVersion POST Refer to 3DS section.
3ds2.authenticationStatus POST Refer to 3DS section.
3ds2.authenticationStatusReason POST Refer to 3DS section.

Refund

Overview

https://api.paymark.nz/transaction/refund

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

Field Name Value Description
paymentId UUID Use if refunding a prior payment.
captureId UUID Use if refunding a prior captured transaction.
Environment URL
Production https://api.paymark.nz/transaction/refund
Sandbox https://apitest.paymark.nz/transaction/refund

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 capture ($54.67), where the ID of the prior capture 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://lgapi.uat.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":"Mirandas Marvellous Muffins",
    "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"
  }
}

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://lgapi.uat.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":"Mirandas Marvellous Muffins",
    "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"
  }
}

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

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of refund resource.
status string Status field of refund resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of refund resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of refund resource.
transactionReference string Merchant reference for a refund.

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']",
        "eci": "XX"
    },
    "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":{
        "systemTraceAuditNumber":"123456789012",
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre']",
        "frequency":"['single'|'recurring']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"12",
        "retrievalReferenceNumber":"123456789012",
        "storedCredentials":"['new'|'stored']
    }
}

Required Fields for Refund

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
card.cardNumber POST Yes
card.expiryDate POST Yes if transaction.frequency is “single”.
merchant.cardAcceptorIdCode POST, GET Yes
merchant.transactionReference POST, GET Optional.
merchant.transactionInformation POST Optional.
merchant.timeStamp POST Optional.
transaction.amount POST Yes
transaction.source POST Optional, uses account default if not present.
transaction.settlementDate POST Optional.

Status Check

Overview

https://api.paymark.nz/transaction/status

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 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
Environment URL
Production https://api.paymark.nz/transaction/status
Sandbox https://apitest.paymark.nz/transaction/status

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",
        "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
    }
}

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://lgapi.uat.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",
    "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

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://lgapi.uat.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",
    "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

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

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of status check resource.
status string Status field of status check resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of status check resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of status check resource.
transactionReference string Merchant reference for a status check.

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="status check reference" 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://lgapi.uat.paymark.nz/transaction/status
     ?cardAcceptorIdCode=850525&transactionReference="status check
      reference",
    "rel": "self"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/status/
            76a1c90c-54c9-4588-8930-4a9b29f0d81b",
    "rel": "76a1c90c-54c9-4588-8930-4a9b29f0d81b"
    }, {
    "href":"https://lgapi.uat.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'|'Merchant']",
        "frequency":"['single'|'recurring'|'unscheduled']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",  
        "storedCredentials":"['new'|'stored']",
        "agreementId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
}

Required Fields for Status Check

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
card.cardNumber POST Yes
card.expiryDate POST Yes if transaction.frequency is “single”.
card.cardHolderName POST Yes
card.cardSecurityCodePresence POST Yes
card.cardSecurityCode POST Yes if cardSecurityCodePresence is “Present”.
merchant.cardAcceptorIdCode POST, GET Yes
merchant.transactionReference POST, GET Optional.
merchant.transactionInformation POST Optional.
merchant.timeStamp POST Optional.
transaction.source POST Optional, uses account default if not present.
transaction.storedCredentials POST Should always be provided for a transaction using a saved (tokenised) card.
transaction.agreementId POST Required if transaction.frequency is not “single”

Authorisation

Overview

https://api.paymark.nz/transaction/authorisation

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.

Environment URL
Production https://api.paymark.nz/transaction/authorisation
Sandbox https://apitest.paymark.nz/transaction/authorisation

Create Authorisation

Creates a new authorisation for processing on the Paymark 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":"5123450000000008",
        "expiryDate":"2039-01",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"100"
    },
    "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",
        "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8",
        "settlementDate":"2015-05-27"
    }
}

Example Request – Creating a 3DS 2 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":"100"
    },
    "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": {
        "protocolVersion":"2.1.0",
        "transactionId":"5646a82d-8b05-40a6-b33e-2038c8670b3a",
        "authenticationStatus":"Y",
        "eci":"02",
        "authenticationStatusReason":"16",
        "authenticationValue":"AAABBQHLYDkkad8AImDLAAAAAAA=",
    }
}

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:

Fields Value Description
cardNumber scheme token DPAN
expiryDate scheme token expiry date
eci scheme token eci value
cryptogram scheme token cryptogram

SCHEME TOKEN TRANSACTION REQUEST GUIDE

Fields Visa Mastercard AMEX
type Required Required Required
cryptogram Required Required -
eci Required Required Required
cardSecurityCode - - Required
expiryDate Required Required Required
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":"2024-03-26T03:14:39.367Z"
    },
    "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://lgapi.uat.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",
    "paymentAccountReference":""
  },
  "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",
    "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

Example Response - 3DS2

HTTP/1.1 201 Created

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

{
    "links": [ 
        {
        "href":"https://lgapi.uat.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",
        "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
    },
    "3ds2": {
        "protocolVersion":"2.1.0",
        "transactionId":"5646a82d-8b05-40a6-b33e-2038c8670b3a",
        "authenticationStatus":"Y",
        "eci":"02",
        "authenticationStatusReason":"16",
        "authenticationValue":"AAABBQHLYDkkad8AImDLAAAAAAA=",
    }
}

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://lgapi.uat.paymark.nz/transaction/authorisation/
            3f83d525-8f50-4261-839e-e56032e1b0d5",
    "rel":"self"
    }
  ],
  "id":"3f83d525-8f50-4261-839e-e56032e1b0d5",
  "status":"complete",
  "creationTime":"2024-03-26T03:14:39.367Z",
  "modificationTime":"2024-03-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"
  }
}

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

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://lgapi.uat.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",
    "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

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

QUERY AUTHORISATION REQUEST

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of authorisation resource.
status string Status field of authorisation resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of authorisation resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of authorisation resource.
transactionReference string Merchant reference for a authorisation.

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://lgapi.uat.paymark.nz/transaction/authorisation
     ?cardAcceptorIdCode=850525&transactionReference="auth reference",
    "rel": "self"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/authorisation/
            5296a82d-8b05-40a6-b33e-2038c8670b3a",
    "rel": "5296a82d-8b05-40a6-b33e-2038c8670b3a"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/authorisation/
            8ca82611-0b78-40ba-94c0-80f3eb208459",
    "rel": "8ca82611-0b78-40ba-94c0-80f3eb208459"
    }, {
    "href":"https://lgapi.uat.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']",
        "paymentAccountReference":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"   
    },
    "dsrp": {
        "tokenType":"['AETS'|'MDES'|'VTS'|'applePay'|'googlePay'|'samsungPay']",
        "tokenPan":"4111111111111111",
        "tokenExpiryDate":"YYYY-MM",
        "tokenSecurityCode":"XXXX",
        "eciIndicator":"XX",
        "cryptogram":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "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": {
        "amount":12345,
        "additionalAmount": {
            "originalAmount": "22345"
        },
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre'|'Merchant']",
        "frequency":"['single'|'recurring'|'unscheduled']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",
        "periodType":"['minutes'|'hours'|'calendar days']",
        "periodDuration":"[1 to 99]",    
        "storedCredentials":"['new'|'stored']",
        "agreementId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    },
    "3ds2": {
        "protocolVersion":"X.X.X",
        "transactionId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "authenticationStatus":"X",
        "eci":"XX",
        "authenticationStatusReason":"XX",
        "authenticationValue":"XXXXXXXXXXXXXXXXXXXXXXXXXXX=",
    }
}

Required Fields for Authorisation

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
card.cardNumber POST Yes for card transactions
card.expiryDate POST Yes for card transactions, if transaction.frequency is “single”.
card.cardSecurityCodePresence POST Yes for card transactions
card.cardSecurityCode POST Yes for card transactions, if cardSecurityCodePresence is “Present”.
card.type POST Yes if transaction is “SCHEME_TOKEN”
card.cryptogram POST Yes if transaction is “SCHEME_TOKEN”, Customer Initiated Transaction and Visa or Mastercard
card.eci POST Yes if transaction is “SCHEME_TOKEN”, Customer Initiated Transaction and Visa or Mastercard
merchant.cardAcceptorIdCode POST, GET Yes
merchant.transactionReference POST, GET Optional.
merchant.transactionInformation POST Optional.
merchant.timeStamp POST Optional.
transaction.amount POST Yes
transaction.source POST Optional, uses account default if not present.
transaction.periodType POST Yes
transaction.periodDuration POST Yes
transaction.frequency POST Optional, uses account default if not present.
Set to “single” for one-off payments or when charging a saved card e.g. the Customer has previously opted to save their Card then chooses to use this for a later purchase.
Set to “recurring” for a Merchant initiated payment where there is an agreement between a Cardholder and a Merchant to bill the Cardholder’s account on a periodic basis without a specified end date e.g. bill payment or subscription.
transaction.agreementId POST Required if transaction.frequency is not “single”
transaction.storedCredentials POST Should always be provided for a transaction using a saved (tokenised) card.
transaction.settlementDate POST Optional.
3ds2.transactionId POST Refer to 3DS section.
3ds2.eci POST Refer to 3DS section.
3ds2.authenticationValue POST Refer to 3DS section.
3ds2.protocolVersion POST Refer to 3DS section.
3ds2.authenticationStatus POST Refer to 3DS section.
3ds2.authenticationStatusReason POST Refer to 3DS section.

Capture

Overview

https://api.paymark.nz/transaction/capture

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

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

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

Environment URL
Production https://api.paymark.nz/transaction/capture
Sandbox https://apitest.paymark.nz/transaction/capture

Create Capture

Creates a new capture for processing on the Paymark 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",
        "settlementDate":"2015-05-28"
    }
}

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://lgapi.uat.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"
  }
}

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://lgapi.uat.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"
  }
}

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

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://lgapi.uat.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"
  }
}

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

QUERY CAPTURE REQUEST

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of capture resource.
status string Status field of capture resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of capture resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of capture resource.
transactionReference string Merchant reference for a capture.

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 reference" 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://lgapi.uat.paymark.nz/transaction/capture?cardAcceptorIdCode=850525&transactionReference=auth%20reference",
    "rel": "self"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/capture/dfdf6f47-462e-442c-89b7-240e82166672",
    "rel": "dfdf6f47-462e-442c-89b7-240e82166672"
    }, {
    "href":"https://lgapi.uat.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":"XXXX",
        "cardSecurityCodeResponse":"['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "paymentAccountReference":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"      
    },
    "dsrp": {
        "tokenType":"['AETS'|'MDES'|'VTS'|'applePay'|'googlePay'|'samsungPay']",
        "tokenPan":"4111111111111111",
        "tokenExpiryDate":"YYYY-MM",
        "tokenSecurityCode":"XXXX",
        "eciIndicator":"XX",
        "cryptogram":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "authorisationId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "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":{
        "amount":12345,
        "currency":"['AUD'|'NZD'|'USD'|...]",
        "source":"['Web Site'|'Call Centre'|'Merchant']",
        "frequency":"['single'|'recurring'|'unscheduled']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",
        "conditionIndicator":"['Partial'|'Final']",
        "storedCredentials":"['new'|'stored']",
        "agreementId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
}

Required Fields for Capture

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
authorisationId POST Yes
merchant.cardAcceptorIdCode GET Optional.
merchant.transactionReference GET Optional.
transaction.amount POST Yes: should be no more than the approved amount of the corresponding authorisation transaction (as referenced by the authorisationId field).
transaction.conditionIndicator POST Yes
transaction.settlementDate POST Optional.

Cancellation

Overview

https://api.paymark.nz/transaction/cancel

A cancellation relates to a matching authorisation, resulting in removal of a hold on Cardholder funds that the Merchant no longer requires.

Once an authorisation has been cancelled, the client should not then attempt a capture against this authorisation.

Notes:

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

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

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

Environment URL
Production https://api.paymark.nz/transaction/cancel
Sandbox https://apitest.paymark.nz/transaction/cancel

Create Cancellation

Creates a new cancellation for processing on the Paymark network. The cancellation must reference a previous authorisation.

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

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://lgapi.uat.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"
  }
}

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

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://lgapi.uat.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"
  }
}

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

QUERY CANCELLATION REQUEST

Name Value Description
cardAcceptorIdCode string Required. cardAcceptorIdCode field of cancellation resource.
status string Status field of cancellation resource.
startTime date/time, ISO 8601 formatted Minimum value of creation field of cancellation resource.
endTime date/time, ISO 8601 formatted Maximum value of creation field of cancellation resource.
transactionReference string Merchant reference for a cancellation.

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 reference" 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://lgapi.uat.paymark.nz/transaction/cancel
     ?cardAcceptorIdCode=850525&transactionReference="auth reference",
    "rel": "self"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/cancel/
            c38c045b-bba4-44c9-95e6-6d24dbf45788",
    "rel": "c38c045b-bba4-44c9-95e6-6d24dbf45788"
    }, {
    "href":"https://lgapi.uat.paymark.nz/transaction/cancel/
            fbdf7cde-e2a3-4aa2-bdba-e7799fdef6f2",
    "rel": "fbdf7cde-e2a3-4aa2-bdba-e7799fdef6f2"
    }
  ],
  "captures": [ {
    "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']",
        "cardSecurityCode":"XXXX",
        "cardSecurityCodeResponse":"['Match'|'No Match'|'Not Processed'|'Not on Card'|'No keys, not certified or both']",
        "paymentAccountReference":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "['CARD'|'SCHEME_TOKEN']",
        "cryptogram": "XXXXXXXXXXXXXXX",
        "eci": "XX"     
    },
    "dsrp": {
        "tokenType":"['AETS'|'MDES'|'VTS'|'applePay'|'googlePay'|'samsungPay']",
        "tokenPan":"4111111111111111",
        "tokenExpiryDate":"YYYY-MM",
        "tokenSecurityCode":"XXXX",
        "eciIndicator":"XX",
        "cryptogram":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "authorisationId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "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'|'Merchant']",
        "frequency":"['single'|'recurring'|'unscheduled']",
        "processorResponseCode":"00",
        "settlementDate":"YYYY-MM-DD",
        "authorisationCode":"123456",
        "retrievalReferenceNumber":"123456789012",
        "systemTraceAuditNumber":"123456789012",
        "storedCredentials":"['new'|'stored']",
        "agreementId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
}

Required Fields for Cancellation

Refer to Field Glossary section for field information.

Name Valid Methods Required?
id GET Yes for read.
status GET Optional.
creationTime GET Optional, can specify startTime or endTime in query.
authorisationId POST Yes
merchant.cardAcceptorIdCode GET Optional.
merchant.transactionReference GET Optional.

Three Domain Secure 3DS

Overview

Linked Gateway provides a 3DS Server. The MPI will orchestrate your request, attempting to authenticate via the most recent 3DS version, and falling back to the version supported by the card issuer if required.

3DS is supported for MasterCard, Visa and American Express.

Orchestrated 3DS Sequence Diagram

See also more information on 3DS data points and flows.

Authentication Preparation Request

POST https://api.paymark.nz//transaction/payment-authentication
RequestsExample with 3DS 2 Frictionless responseExample with 3DS 2 Challenge/Method Flow response
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
    "card": {
        "cardNumber": "4000000000000002",
        "expiryDate": "2021-07"
    },
    "merchant": {
        "cardAcceptorIdCode": "123456",
        "transactionReference": "Test Reference"
    },
    "transaction": {
        "amount": "10000",
        "currency": "NZD",
        "dateTime": {{timestamp}},
        "description": "Test"
    },
    "messageCategory": "PaymentAuthentication",
    "threeDsRequestorInformation": {
        "authenticationIndicator" : "paymentTransaction"
    },
    "threeDSSessionData": "c2773bec-5717-4564-816e-7897cfd6d7f3",
    "notificationUrl": "https://api.csp.co.nz/threedsecure-notifications",
    "browser": {
        "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "javaEnabled": true,
        "language": "en-nz",
        "colorDepth": "32bits",
        "screenHeight": 480,
        "screenWidth": 640,
        "timeZone": -780,
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0",
        "ipAddress": "2001:0db8:0000:0042:0000:8a2e:0370:7334"
    }
}
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "protocolVersion": "2.1.0",
  "authenticationSessionId": "88efbde4-41c5-4bda-91e1-dba569f51a4c",
  "mpiTwo": {
    "threeDSServerTransactionId": "98094f12-5ee4-4116-934f-f29a78240609",
    "authenticationResponse": {
      "transStatus": "Succeeded",
      "authenticationValue": "U3VjY2Vzc2Z1bHkgYXV0aGVudGk=",
      "authenticationStatus": "Y",
      "eci": "05",
      "acsUrl": "https://mpi-v2-simulation.test.v-psp.com/acs-simulation/challenge?redirectUrl=https://api.csp.co.nz/threedsecure-notifications",
      "whitelist": {},
      "cardholderInformation": "Message for the cardholder",
      "authenticationResponse": "eyJhY3NDaGFsbGVuZ2VNYW5kYXRlZCI6Ik4iLCJhY3NPcGVyYXRvcklEIjoiQWNzT3BJZCAxMTExMTExMTExIiwiYWNzUmVmZXJlbmNlTnVtYmVyIjoiM0RTX0xPQV9BQ1NfUFBGVV8wMjAxMDBfMDAwMDkiLCJhY3NUcmFuc0lEIjoiQzM0Q0FCOEUtOEY0NS00ODI0LUE1RkQtMDI1M0M1RTdFRkZDIiwiYWNzVXJsIjoiaHR0cHM6Ly9tcGktdjItc2ltdWxhdGlvbi50ZXN0LnYtcHNwLmNvbS9hY3Mtc2ltdWxhdGlvbi9jaGFsbGVuZ2U_cmVkaXJlY3RVcmw9aHR0cHMlM0ElMkYlMkZoMW1tdjZlNng5LmV4ZWN1dGUtYXBpLmFwLXNvdXRoZWFzdC0yLmFtYXpvbmF3cy5jb20lMkZhZG1pbiUyRmh0dHBfc2xhY2tfZm9yd2FyZGVyIiwiYXV0aGVudGljYXRpb25UeXBlIjoiMDIiLCJhdXRoZW50aWNhdGlvblZhbHVlIjoiVTNWalkyVnpjMloxYkhrZ1lYVjBhR1Z1ZEdrPSIsImNhcmRob2xkZXJJbmZvIjoiTWVzc2FnZSBmb3IgdGhlIGNhcmRob2xkZXIiLCJkc1JlZmVyZW5jZU51bWJlciI6IkRTX0xPQV9ESVNfUFBGVV8wMjAxMDBfMDAwMTAiLCJkc1RyYW5zSUQiOiJmMjUwODRmMC01YjE2LTRjMGEtYWU1ZC1iMjQ4MDhhOTVlNGIiLCJlY2kiOiIwNSIsInRyYW5zU3RhdHVzIjoiWSIsInRyYW5zU3RhdHVzUmVhc29uIjoiMTYiLCJtZXNzYWdlVHlwZSI6IkFSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI5ODA5NGYxMi01ZWU0LTQxMTYtOTM0Zi1mMjlhNzgyNDA2MDkifQ",
      "transactionId": "ZjI1MDg0ZjAtNWIxNi00YzBhLWFlNWQtYjI0ODA4YTk1ZTRi",
      "authenticationStatusReason": "16",
      "authenticationReference": "C34CAB8E-8F45-4824-A5FD-0253C5E7EFFC"
    }
  }
}
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
    "card": {
        "cardNumber": "4000000000000002",
        "expiryDate": "2021-07"
    },
    "merchant": {
        "cardAcceptorIdCode": "123456",
        "transactionReference": "Test Reference"
    },
    "transaction": {
        "amount": "10000",
        "currency": "NZD",
        "dateTime": {{timestamp}},
        "description": "Test"
    },
    "messageCategory": "PaymentAuthentication",
    "threeDsRequestorInformation": {
        "authenticationIndicator" : "paymentTransaction"
    },
    "threeDSSessionData": "c2773bec-5717-4564-816e-7897cfd6d7f3",
    "notificationUrl": "https://api.csp.co.nz/threedsecure-notifications",
    "browser": {
        "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "javaEnabled": true,
        "language": "en-nz",
        "colorDepth": "32bits",
        "screenHeight": 480,
        "screenWidth": 640,
        "timeZone": -780,
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0",
        "ipAddress": "2001:0db8:0000:0042:0000:8a2e:0370:7334"
    }
}
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "protocolVersion": "2.1.0",
  "authenticationSessionId": "9ee44660-ac34-4d9e-92b0-4ced32837b5b",
  "mpiTwo": {
    "threeDSServerTransactionId": "4dcd5158-5fa8-4e16-83ae-58e587628319",
    "methodUrl": "https://mpi-v2-simulation.test.v-psp.com/acs-simulation/method-url",
    "redirectionFormData": {
      "action": "https://mpi2.test.v-psp.com/3ds-method-redirection/9ee44660-ac34-4d9e-92b0-4ced32837b5b/Visa",
      "values": {
        "methodUrl": "https://mpi-v2-simulation.test.v-psp.com/acs-simulation/method-url",
        "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjRkY2Q1MTU4LTVmYTgtNGUxNi04M2FlLTU4ZTU4NzYyODMxOSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL21waTIudGVzdC52LXBzcC5jb20vM2RzLW1ldGhvZC1yZWRpcmVjdGlvbi85ZWU0NDY2MC1hYzM0LTRkOWUtOTJiMC00Y2VkMzI4MzdiNWIvVmlzYS9yZXF1ZXN0L2NhbGxiYWNrIn0"
      }
    }
  }
}

Authentication Preparation Request
POST/transaction/payment-authentication

You’ll first make a request to /transaction/payment-authentication with a minimum required set of data. The MPI will carry out an Authentication Preparation Request to determine which 3DS Version will be used. The version will be indicated in the response body by the name of the top level JSON object: mpiOne or mpiTwo.

Should the response body contain mpiTwo and an authenticationResponse object, the authentication has been carried out in a frictionless manner and is complete - the authenticationResponse object will contain all the fields required to process the transaction.


Send redirectionFormData to ACS/Method URL

POST https://api.paymark.nz//https:/mpi-v1-simulation.test.v-psp.com/acs/checkauthentication?parameters=iRm%2bmE0W%2buGSVM7FCiPYyHQrxY9p9%2fOXPsgO36KEqF8%3d
RequestsSend data to ACS
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/x-www-form-urlencoded
Body
MD=123456789012346890&pareq=1234567890
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0

Send redirectionFormData to ACS/Method URL
POST/{actionUrl}

Should the response body contain a redirectionFormData object, the properties should be posted to the actionUrl in x-www-form-urlencoded format. The ACS or 3DS Method server will POST the result of the authentication to the notificationUrl provided in the Authentication Preparation Request.

URI Parameters
HideShow
actionUrl
string (required) Example: https://mpi-v1-simulation.test.v-psp.com/acs/checkauthentication?parameters=iRm%2bmE0W%2buGSVM7FCiPYyHQrxY9p9%2fOXPsgO36KEqF8%3d

Issuer’s ACS or Method flow URL, aseturned by LG in authentication preparation response.


Receive authentication outcome on Notification URL

POST https://api.paymark.nz//
RequestsReceive 3DS 2 Frictionless Method Flow resultReceive 3DS 2 challenge flow result
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/x-www-form-urlencoded
Body
threeDSSessionData=123456789012346890&cres=
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/x-www-form-urlencoded
Body
threeDSSessionData=123456789012346890&cres=1234567890
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0

Receive authentication outcome on Notification URL
POST/

Based on what is received by your notificationUrl, you’ll need to formulate a Finalise Authentication request to /transaction/payment-authentication/{{authenticationSessionId}}/authentication-response as follows:

  • Parameters

    + notificationUrl: `https://api.csp.co.nz/threedsecure-notifications` (required, string) - the URL where you will receive notifcations from the issuer ACS. You define this in the authenticationPreparationRequest

Finalise Authentication Request

PUT https://api.paymark.nz//transaction/payment-authentication/authentication-response
Requests3DS 2 Challenge3DS 2 Frictionless Method Flow
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Body
{
  "mpiTwoResponse": {
    "cres": "{cres}"
  }
}
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "transactionId": "string",
  "authenticationStatus": "Unknown",
  "eci": "string",
  "authenticationValue": "string",
  "cavvAlgorithm": "string",
  "authenticationStatusReason": "string"
}
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Body
{
  "mpiTwoResponse": {
    "cres": ""
  }
}
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "transactionId": "string",
  "authenticationStatus": "Unknown",
  "eci": "string",
  "authenticationValue": "string",
  "cavvAlgorithm": "string",
  "authenticationStatusReason": "string"
}

Finalise Authentication Request
PUT/transaction/payment-authentication/authentication-response

Data received at notificationUrl Finalise Authentication Request body
threeDsSessionData and cres mpiTwoResponse.cres = “cres value”
threeDsSessionData and empty cres mpiTwoResponse.cres = “”

The response to this request will give you the fields required to process the transaction.

  • Parameters

    + authenticationSessionId: `381a08c8-9189-4995-b07b-6c3821f70e35` (required, string) - UUID representing the athentication session. Returned by LG in authentication preparation response.

Field Glossary

General Fields

Field Name Type Format or Example Description
id string “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Paymark-generated globally unique identifier for the resource.
status string " [ ‘created’ | ‘processing’ | ‘complete’ | ‘failed’ ] " Status of the resource. One of:
* created - resource has been created but processing has not been started.
* processing - processing of the resource is currently in progress.
* complete - processing of the resource has been completed. This does not imply an approval or decline, only that processing has completed. See also transaction.processorResponseCode.
* failed - processing of the transaction has failed due to a technical fault.
creationTime date/time as ISO 8601 string “YYYY-MM-DDThh:mm:ss.000Z” Date/time at which the resource was created.
modificationTime date/time as ISO 8601 string “YYYY-MM-DDThh:mm:ss.000Z” Date/time at which the resource was last updated.
authorisationId string “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Identifier of a previous authorisation resource which relates to this (capture or cancellation) transaction.
paymentId string “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Identifier of a previous payment resource which relates to this (refund) transaction.

card Object

Field Name Type Format or Example Description
cardNumber string, length minimum 13, maximum 19 4111111111111111 Card number / PAN to be used for payment. Card numbers must be ephemeral only and never stored. If provided, the Card number will be tokenised and the token returned in lieu of the Card number.
expiryDate string “YYYY-MM” The month/year when the Card expires.
cardSecurityCodePresence enumeration as string " [ ‘Not Present’ | ‘Present’ | ‘Not Legible’ | ‘Not Imprinted’ ] " An indication of the presence of the card security code (CSC / CVV). One of:
* Not Present - No CSC was provided.
* Present - CSC was provided.
* Not Legible - No CSC was provided because it was not legible on the card.
* Not Imprinted - No CSC was provided because it was not imprinted on the card.
cardSecurityCode string, length minimum 3, maximum 4 “1234” The card security code (CSC / CVV) that is printed on the back of the Card.
cardSecurityCodeResponse enumeration as string " [ ‘Match’ | ‘No Match’ | ‘Not Processed’ | ‘Not on Card’ | ‘No Keys, not certified or both’ ] " The result of looking up the Card’s CSC. One of:
* Match - The CSC was checked and was correct.
* No Match - The CSC was checked and was incorrect.
* Not Processed - The CSC was not checked.
* Not on Card.
* No Keys, not certified or both.
cryptogram enumeration as string AwAAAAAAPboI4MoAmZZRghEAAAA= Helps authenticate and protect the integrity of electronic transactions
type enumeration as string " [ ‘SCHEME_TOKEN’ | ‘CARD’ ] " Identifies the transaction request is for CARD or SCHEME_TOKEN
eci enumeration as string " [ ‘00’ | ‘01’ | ‘02’ | ‘05’ | ‘06’ | ‘07’ ] " Electronic commerce indicator received during the Scheme Tokenisation process.

merchant Object

Field Name Type Format or Example Description
cardAcceptorIdCode string, length minimum 1, maximum 15 “850525” Paymark-issued identifier for the Merchant. Also known as the MID or Merchant ID.
terminal string “85052501” Paymark-issued terminal identifier for the Merchant.
transactionReference string, length minimum 1, maximum 40 “My unique reference” Optional Merchant supplied transaction reference. Accepted special characters: _ @ . , ! # & $ " ’ ( ) - \ / : { }
transactionInformation string, length minimum 1, maximum 40 “My supporting information” Optional Merchant supplied transaction information. Accepted special characters: _ @ . , ! # & $ " ’ ( ) - \ / : { }
timeStamp string “YYYY-MM-DDThh:mm:ss.000Z” UTC date/time at the transaction source according to the Merchant, as ISO 8601 string. Linked Gateway 2.0 currently overwrites this field with UTC upon receipt.
acquiringInstitutionId string “500051” Acquiring institution ID of the Bank to which the Merchant belongs.
cardAcceptorName string “Saisais Sushi” Merchant’s trading name as provided by the Bank.
street string “5 The Parade” Merchant’s street address as provided by the Bank.
suburb string “Christchurch Valley” Merchant’s address suburb as provided by the Bank.
city string “Christchurch” Merchant’s address city as provided by the Bank.
country string “New Zealand” Merchant’s address country as provided by the Bank.
postalCode string “8000” Merchant’s address post code as provided by the Bank.
mcc string “1234” Classification code as provided by the Bank.

transaction Object

Field Name Type Format or Example Description
systemTraceAuditNumber string “123456789” Once the transaction status is complete, the Paymark-assigned transaction identifier.
amount integer, length minimum 2, maximum 9 12345 The amount of the transaction represented as the smallest unit of the currency. For NZD this will be a whole number of cents. For example, $12.50 is represented as 1250. For JPY, there are no cents, so ¥1250 is represented as 1250.
Notes:
* This field must be omitted for a status check and cancellation.
* Refer to ISO 4217 for more information on currency units.
additionalAmount. originalAmount integer, length minimum 2, maximum 9 12345 The requested amount of the transaction represented as the smallest unit of the currency. For NZD this will be a whole number of cents. For example, $12.50 is represented as 1250. For JPY, there are no cents, so ¥1250 is represented as 1250. This is present when an authorisation has been approved for a lesser amount than that requested. The approved amount is shown in the amount field.
currency string, ISO 4217 currency code " [ ‘AUD’ | ‘NZD’ | ‘USD’ | … ] " Optional. The currency of the amount, for example NZD. If the currency is not specified, the Merchant’s default will be used. Currencies currently supported by our banks include: ‘AUD’, ‘CAD’, ‘CHF’, ‘CNY’, ‘DKK’, ‘EUR’, ‘GBP’, ‘HKD’, ‘JPY’, ‘KRW’, ‘MYR’, ‘NOK’, ‘NZD’, ‘SEK’, ‘SGD’, ‘USD’, ‘ZAR’. Other currencies will return an error.
source enumeration as string " [ ‘Web Site’ | ‘Call Centre’ | ‘Merchant’ ] " Optional. The source of the transaction. Captures who/what system handled the card data. If the source is not specified, the Merchant’s default will be used. Currently the API supports:
* Web Site - online eCommerce transaction.
* Call Centre - details were manually entered by the Merchant.
* Merchant - for Merchant Initiated transactions.
processorResponseCode string “0A” The result of processing the transaction. This can be used to determine whether the transaction was approved or declined. Available once the transaction status is “complete”. Note: For an authorisation request, the processorResponseCode = 10 indicates a partial authorisation, that is, less funds have been approved than were requested. The approved amount is shown in the amount field and the requested amount is shown in the additionalAmount.originalAmount field. Take care to ensure the maximum capture limit is adhered to i.e. “amount”.
periodType enumeration as string " [ ‘minutes’ | ‘hours’ | \’calendar days\’ ] " For an authorisation, an indicator of what type of duration has been passed in the periodDuration field. One of:
* minutes
* hours
* calendar days
Note: This field must be omitted for a status check.
periodDuration integer, range 1 to 99 “7” For an authorisation, the amount of time for which the authorised funds should be held. The periodType field indicates whether this value represents minutes, hours or calendar days. Note: This field must be omitted for a status check.
frequency enumeration as string " [ ‘single’ | ‘\recurring’ | ‘instalment’ ] " Indicates whether this is a single, recurring, or instalment transaction. If the frequency is not specified, the Merchant’s default will be used. An indication of whether this is a one-off or repeat transaction. One of:
* single – one-off transaction, or Customer initiated payment on a saved card.
* recurring - an agreement between a Cardholder and a Merchant to bill the Cardholder’s account on a periodic basis without a specified end date e.g. bill payment or subscription.
* instalment - an agreement between a Cardholder and a Mrchant to bill the Cardholder’s account where the number of payments is limited e.g. a purchase split over multiple payments.
Note: Expiry Date must be sent with the first recurring transaction processed for a particular Card. Thereafter expiry date is optional. However, some Issuers may decline transactions if the expiry date is not present.
settlementDate string “YYYY-MM-DD” An identification of which batch of transactions this transaction belongs to. Represents the date on which the funds were/will be transferred. The default settlement cut off time for Linked Gateway 2.0 clients is 2159, that is, any transactions done up to 21:59:59 will be included in “today’s” settlement. Any transactions after this time will be included in “tomorrow’s” settlement. If not specified in the request, this information is available once the transaction status is “complete”. If a future settlement date is required, this can be specified in a payment, refund, authorisation or capture request. In the event a settlement day of “today” is specified from 2200 onwards, Linked Gateway 2.0 will update this to “tomorrow” in the response. If using the settlement date field in the request, the client should pay attention to the settlement date received in the response. This field is not searchable, but is returned in the GET or query response (using other search criteria). This field is not permitted in a status check or cancellation request; however it is provided in the response.
authorisationCode string, length minimum 0, maximum 6 “6” An identification of the authorisation performed by the processor.
retrievalReferenceNumber string “123456789012” The Acquirer transaction identifier, RRN. Available once the transaction status is “complete”.
token string “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” UUID for this transaction.
maskedNumber string “XXXXXX…XXXX” Masked Card number (PAN).
conditionIndicator enumeration as string " [ ‘Partial’ | ‘Final’ ] " Indicates the lifecycle stage of the capture transaction. “Partial” is used when the Cardholder has received an agreed portion of the goods or services. This indicates that there will be more transactions to follow. This transaction is required for Merchants who support multiple capture transactions. “Final” is used when the Cardholder has received all the goods or services. This indicates that no more transactions are expected. This transaction is required for all Merchants who support capture transactions. Note: This is case sensitive and uses camel case.
storedCredentials enumeration as string " [ ‘new’ | ‘stored’ ] " For tokenised transactions, indicates whether a Card was saved (tokenised) as part of this transaction (new), or an existing card token was used (stored). Note: This is case sensitive and uses lower case.
identifierType enumeration as string " [ ‘Visa Checkout’ | ‘Masterpass’ ] " Indicates this transaction used Visa Checkout or a Mastercard Masterpass digital wallet. Needs to be used in conjunction with identifier. Not permitted on a 3DS transaction.
identifier string “XXXXXXXXXXXXXXX” The Visa Checkout / Mastercard Masterpass digital wallet identifier. Needs to be used in conjunction with identifierType. Not permitted on a 3DS transaction. Notes:
* Visa Checkout Identification Reference (VCIND) is 12 bytes. This is in the format *VA*\0016V212XXXXXXXXXXXX, where XXXXXXXXXXXX is the actual VCDAT data.
* Mastercard Masterpass digital wallet identifier is 3 bytes. This is in the format *PP*\00072603XXX, where XXX is the PPOL indicator. 101 = PPOL (Masterpass) Remote, where the wallet data was created by the Cardholder entering information.
agreementId string “XXXXXXXXXXXXXXX” Used in conjunction with Merchant Initiated Transactions.

Test Card Details

Overview

This section details the test cards that may be used in the Linked Gateway 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.

Card Type Card Number Card Expiry (MM/YY) CSC Transaction Status
MasterCard 3D Secure 5123450000000008 01/39 100 Successful
MasterCard 3D Secure 2223000000000007 08/28 100 Timed Out
MasterCard 3D Secure 5123450000000008 05/39 100 Declined
MasterCard 3D Secure 2223000000000007 04/27 100 Expired Card
MasterCard 5111111111111118 01/39 100 Successful
Visa 3D Secure 4508750015741019 01/39 100 Successful
Visa 3D Secure 4508750015741019 08/28 100 Timed Out
Visa 3D Secure 4508750015741019 05/39 100 Declined
Visa 3D Secure 4508750015741019 04/27 100 Expired Card
Visa 4012000033330026 01/39 100 Successful
AMEX 3D Secure 345678901234564 01/39 1000 Successful
AMEX 3D Secure 345678901234564 08/28 1000 Timed Out
AMEX 3D Secure 345678901234564 05/39 1000 Declined
AMEX 3D Secure 345678901234564 04/27 1000 Expired Card
AMEX 3D Secure 371449635398431 01/39 1000 Successful

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

Card Type Card Number Card Expiry (MM/YY) CSC Response Code Transaction Status
MasterCard 5123456789012346 12/20 111 00 Successful
MasterCard 5290075430806729 12/20 111 01 Bank Declined Transactions
MasterCard 5538737873773631 12/20 111 05 Bank Declined Transactions
MasterCard 5265340072069809 12/20 111 12 Transaction Type Not Supported
MasterCard 5307995509923512 12/20 111 31 Bank Declined Transactions
MasterCard 5114996316783803 12/20 111 51 Insufficient Funds
MasterCard 5178468787602840 12/20 111 54 Expired Card
MasterCard 5510545567805243 12/20 111 91 Error Communicating with Bank (Check Card Details)
MasterCard 2221006789012347 12/20 111 00 Successful
MasterCard 2221005430806727 12/20 111 01 Declined
MasterCard 2221007873773638 12/20 111 05 Declined
MasterCard 2221000072069809 12/20 111 12 Declined
MasterCard 2221005509923510 12/20 111 31 Declined
MasterCard 2221006316783808 12/20 111 51 Declined
MasterCard 2221008787602848 12/20 111 54 Declined
MasterCard 2221005567805245 12/20 111 91 Declined
MasterCard 5391715789309969 12/20 111 10 Partial authorisation (half requested amount)
MasterCard 3D Secure 5422882800700007 12/20 111 00 Successful
MasterCard 3D Secure 2239468872817471 12/20 111 00 Successful
MasterCard 3D Secure 2239464831923120 01/20 123 10 Partial authorisation (half requested amount)
MasterCard 3D Secure 5257221203980330 01/20 123 00 Successful (blank AAV)
MasterCard 3D Secure 5573216845946050 01/20 123 00 Successful (blank AAV)
MasterCard 3D Secure 5583731329831220 01/20 123 00 Attempted Authentication (blank AAV)
VISA 4987654321098769 12/20 111 00 Successful
VISA 4929474753922860 12/20 111 01 Bank Declined Transactions
VISA 4539032811676621 12/20 111 05 Bank Declined Transactions
VISA 4886709226179775 12/20 111 12 Transaction Type Not Supported
VISA 4556989846299273 12/20 111 31 Bank Declined Transactions
VISA 4556989785924709 12/20 111 51 Insufficient Funds
VISA 4916146026583852 12/20 111 54 Expired Card
VISA 4929233907988775 12/20 111 91 Error Communicating with Bank (Check Card Details)
VISA 4556286124462032 12/20 111 10 Partial authorisation (half requested amount)
VISA 3D Secure 4918914107195005 12/20 111 00 Successful
VISA 3D Secure 4988721001931418 12/20 111 00 Card Not Enrolled
American Express 345678901234564 12/20 1111 00 Successful
American Express 372230337931151 12/20 1111 01 Bank Declined Transactions
American Express 374991708241573 12/20 1111 05 Bank Declined Transactions
American Express 371142424142835 12/20 1111 12 Transaction Type Not Supported
American Express 379864718969977 12/20 1111 31 Bank Declined Transactions
American Express 377799096385150 12/20 1111 51 Insufficient Funds
American Express 379269138331578 12/20 1111 54 Expired Card
American Express 375811155501015 12/20 1111 91 Error Communicating with Bank (Check Card Details)

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

Processor Response Codes

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

Acquirer Response Code Response Description
00 Approved or Completed Successfully.
01 Refer to Card Issuer.
02 Refer to Card Issuer’s special condition.
03 Invalid merchant.
04 Pick-up Card.
05 Do not Honour.
07 Special conditions.
08 Honour with Identification (does not apply to eCommerce).
09 Duplicate transmission.
10 Partial Approval.
12 Invalid Transaction.
13 Invalid amount.
14 Invalid card number.
15 Transaction destination for routing not found.
19 Re-enter transaction.
21 No Action Taken.
23 Unacceptable fee.
30 Format Error.
31 Bank Not Supported by Switch.
33 Expired card.
34 Suspected fraud.
35 Card acceptor contact acquirer.
36 Restricted card.
37 Card acceptor call acquirer’s security department.
38 Allowable PIN tries exceeded.
39 No Credit Account.
40 Requested function not supported.
41 Lost card.
42 No universal account available.
43 Stolen Card, Pick Up.
44 No investment account available.
51 Not Sufficient Funds.
52 No Cheque Account.
53 No Savings Account.
54 Expired card.
55 Incorrect PIN.
56 No card record.
57 No account of type requested.
58 Transaction not permitted to Terminal.
59 Suspected fraud.
60 Card acceptor contact acquirer.
61 Exceeds Withdrawal Amount Limits.
62 Permanent restraint (return card).
63 Security violation.
64 Do not honour.
65 Exceeds Withdrawal Frequency Limits.
66 Card acceptor call acquirer’s security department.
67 Do not honour.
75 Allowable Number of PIN Tries Exceeded.
76 Encryption key sync error.
83 Do not send again.
87 Item specified in error.
88 Information unavailable.
89 Card Verification Value (CVV) verification failed.
90 Cutover in process.
91 Issuer or Switch Inoperative.
92 No routing available for the transaction.
93 Violation of law.
94 Duplicate Transmission.
96 System Malfunction.
98 MAC error.
Various 6, 18, 20, 25, 29, 70, 79, 82, 83, 84, 86, 95, 97 are not specified in the Paymark ISO Specification, but have been previously implemented by acquirers. These are mapped to Bank error.

Revision History

Date Update
9 April 2021 First publication online.

Generated by aglio on 14 Oct 2024