Online EFTPOS API

Overview

This document describes the Online EFTPOS API and is designed for:

  • Merchants that have total control over payment experience on their website (i.e. not using any eCommerce platform).

  • eCommerce platform developers who would like to add Online EFTPOS as the alternative payment method to their functionality.

  • CSPs who are processing payments on behalf of a Merchant.

Merchants that use an eCommerce platform and would like to add Online EFTPOS as an alternative payment method should contact their eCommerce platform developer to enable Online EFTPOS on their site. Merchants should also contact Paymark to set up an Online EFTPOS faciltiy via the contact form on the Paymark website.

This API enables Merchants and CSPs to submit payment requests directly to the Consumer’s mobile banking app. Payments can also be partially or completely refunded (conditions apply).

Online EFTPOS is a server to server API, that is, the Consumer’s web browser sends a request to Merchant’s web server and the Merchant’s web server sends the request to the Online EFTPOS API.

ASB, Heartland Bank, The Co-operative Bank and Westpac customers can use Online EFTPOS.

ASB customers can also use the Autopay (Trusted Payment) feature.

Integrators can create a Sandbox account here.

Connections

Transport

The Online EFTPOS 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 Accept and Authorization headers. See also World Wide Web Consortium protocol specification.

The Accept header is used to specify the content type that your API client will accept.

Online EFTPOS uses application/vnd.paymark_api+json 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 the Online EFTPOS API.

Versioning

You should expect that the Online EFTPOS API will evolve over time as Paymark adds new features. Your parser should not rely on fields being in a particular order and should ignore any fields that you do not expect to receive.

Endpoints

The base URL for all Online EFTPOS Production endpoints is https://api.paymark.nz/.

The base URL for all Online EFTPOS Sandbox endpoints is https://apitest.paymark.nz/. This URL is used in response examples in this specification. This environment is used for testing API development.

The endpoints available are:

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

  • /transaction/oepayment/ to create new payment requests, and query the status of previous requests.

  • /transaction/oerefund/ to create new refund requests, and query the status of previous requests.

  • /oemerchanttrust/ to search and manage Autopay (Trusted Payment) arrangements.

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

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

Security

Paymark requires that all connections are encrypted with TLS; there are no unencrypted endpoints available. Your API client must properly validate the TLS trust chain to ensure that your connection to Paymark is secure. You must connect with TLS 1.2 or higher.

Authentication

The Online EFTPOS API uses the OAuth 2.0 client credentials flow for authentication (as detailed in the Internet Engineering Task Force flow).

You need to register your app to get a Consumer Key and Consumer Secret. You must protect these credentials.

Different credentials will be provided for each environment (Production and Sandbox). Contact Paymark to get your credentials for the applicable environment.

Bearer Token

Before calling any Online EFTPOS 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.

The bearer token request header should contain authorisation that is Base64 encoded. The format is ConsumerKey:ConsumerSecret.

POST https://apitest.paymark.nz/bearer/
Requestswith body
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic (Base64 encoded authorisation)
Body
grant_type:client_credentials
Responses200
Headers
Content-Type: application/json
Body
{
  "issued_at": "1464126466974",
  "application_name": "111111-2c4e-42cc-b613-fe974111111a",
  "scope": "",
  "status": "approved",
  "expires_in": "3599",
  "token_type": "BearerToken",
  "client_id": "axxxxxxxxxxx",
  "access_token": "bxxxxxxx"
}

Create Bearer Token
POST/bearer/

Create a Bearer Token for a transaction.


Message Signature

Messages sent to the API client from Paymark must be signed, so that the API client can verify that Paymark sent the message, and that it was not modified while in transit.

The signing algorithm used is RSA with SHA512.

The public signing key for the Sandbox environment is shown in the Sandbox section.

The public signing key for the Production environment is shown below.

-----BEGIN PUBLIC KEY-----

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAzu1yVLwgmGoX+MwTsql9
+8dX219WYqMcqjJReJwl/rY2P0Z7mCOhHlnF5nr6RfzBhYZI2QjOcWx7/Eu4A/zN
MYNL3XPJ0Iib0ml+54ACVUCVkrl7EtKTmR7TpFHUktT2jRNGsD2iU+lqAmxQgDnx
kAoznhbzeDVG4oRZu1d0WeMNy1RIZMddO32iAgzRxsgIzpX1vZTIZ2OASnYVURLq
ktTQqgBe8Yhn2FuQjadm8cEjp8BaNyQSpusnIO7d+wOqMQnUc+W4IgS9JBEXM+Qq
frgZZ99RRaFcG/UwR50qAmud5XC2vGHZSonUUlmx8rnUpuNGLiFKQ37PXzcDOVvv
o2VBey9Lss04GRneGcYc2SHQj88/GSil/293sT0s+vcUJ0uccgYcAmV2sgQn2ok4
/VXuGkChj9+mx0DulUpuj3NMAf2Rh4Av+Vpl20LHbcAoA1kY9kBRHGCjEq07Mw0Y
dsuS/aAIxhZIxWdac9Sis7S2mP+D8CeJw2dymT10mZMYgkcv8RbEhzwDfLVgp52/
ogRfVIJ3SEmIkdxqVgUtCycldnhsu/Ql1xjAWMHZwDCpz9RUhB49IZ3iOdCt/zAi
gV511KaCjStFn03m5QUzf76jJgqKaFRXIxUKoZwmMGl2SDBhACP9o0+pTam3Za+E
TSO4jhCzXDfUWA/BE5yLywECAwEAAQ==

-----END PUBLIC KEY-----

Methods

This section describes the methods that may be used to create Online EFTPOS payments, including using open.js to manage the payment form experience, accepting Autopay (Trusted) payments, and initiating refunds. This section also details how to query payment, Autopay and refund details.

open.js Payment

open.js is the JavaScript framework that allows API Clients to build payment flows that support various Open Payments Platform (OPEN) integrations.

The open.js plugin enables the easiest Online EFTPOS integration as it handles the creation of the Online EFTPOS payment form and manages the transaction flows.

API Clients who manage their own payment page need to refer to Online EFTPOS payments.

An API client must be either a:

  • Registered Merchant with permissions to process payments via this API or,

  • CSP with a contract with a registered Merchant to process transactions on their behalf.

If the API client does not have processing rights for any features documented below, the request will fail.

Getting Started

An open.js payment flow consists of the following steps:

X-Parent-Referer Header

The X-Parent-Referer header is used as part of the authentication mechanism to validate who the requests to the open.js API are sent by. It contains the url of the page hosting the the open.js payment form. To authorise requests from your web site you will need to update the list of http referral URLs in OE Portal to contain all the domains of your web sites where open.js will be used.

Session

A Session contains the details of your Customer’s intent to purchase. You create a Session when your Customer wants to pay for something through open.js. In doing so you will be given a session ID.

Loader

The Loader is a lightweight JavaScript package that loads the payment form that allows your Customer to initiate a payment request.

This is the second step in the open.js payment flow.

The package exposes an openjs.init() function that accepts a sessionId. Calling openjs.init() will do the following:

  • Create an iframe element.

  • Set the src of the iframe to be the URL of the open.js iframe application.

  • Append the iframe element to the DOM in a div with an id specified by the Merchant.

You can insert this code snippet into the location on your web site that you wish to surface the payment form.

<script type="text/javascript" src="https://open.demo.paymark.co.nz/v1/loader/open.js"></script>
<script>
    const urlParams = new URLSearchParams(window.location.search)
    const sessionId = urlParams.get('sessionId')
    if (window.openjs) {
    window.openjs.init({
        sessionId: sessionId,
        elementId: 'openjs-wrapper',
    })
    }
</script>

Security

If you have deployed a Content Security Policy, the full set of directives that open.js requires are below.

Sandbox

connect-src: https://open.demo.paymark.co.nz
frame-src: https://open.demo.paymark.co.nz
script-src: https://open.demo.paymark.co.nz

Production

connect-src: https://open.paymark.co.nz
frame-src: https://open.paymark.co.nz
script-src: https://open.paymark.co.nz
POST https://apitest.paymark.nz/openjs/v1/session
Requestswith body
Headers
Accept: application/json
Content-Type: application/json
Authorization: Bearer access_token
Body
{
  "amount": 1000,
  "redirectUrl": "https://www.widgets.co.nz/cart?order=146",
  "currency": "NZD",
  "description": "Widgets",
  "merchantIdCode": "301234567",
  "orderId": "146",
  "transactionType": "REGULAR"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "amount": 1000,
  "redirectUrl": "https://www.widgets.co.nz/cart?order=146",
  "currency": "NZD",
  "description": "Widgets",
  "merchantIdCode": "301234567",
  "orderId": "146",
  "transactionType": "REGULAR",
  "status": "SESSION_CREATED",
  "id": "0f0451d5-45ab-492d-beb9-6e06b6735d80"
}

Create a Session
POST/openjs/v1/session

The Session request is a server to server request and includes the Merchant details and payment amount. This model is used to ensure the information received from the payment form loaded in the Merchant web site is insufficient to initiate a payment and that the core payment details cannot be tampered with.

This is the first step in the open.js payment flow.

Available Fields

These fields may be used in requests.

Name Type Required Notes
allowAutopay string N Valid values: “true”, “false”.
amount integer Y Must be a positive amount. Amount is in cents.
redirectUrl string N Must be https, no port numbers allowed. If provided, the Consumer will be presented with the option to be redirected to the specified url upon completion of the transaction.
currency string Y Must be “NZD”.
description string Y Merchant’s internal description of the payment, maximum of 20 characters.
Allowed characters: /^[ A-Za-z0-9.,\-]*$/
merchantIdCode string Y Provided by Paymark.
orderId string Y This is used on the Consumer’s bank statement and will be truncated at 12 characters. We recommend a maximum of 12 characters is used in this field. This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.
Allowed characters: /^[ A-Za-z0-9\-]*$/
transactionType string Y Valid values: “REGULAR”, “TRUSTED”, “TRUSTSETUP”

GET https://apitest.paymark.nz/openjs/v1/session/0f0451d5-45ab-492d-beb9-6e06b6735d80
Requestswith body
Headers
Accept: application/json
X-Parent-Referer: https://www.widgets.co.nz
Responses200
Headers
Content-Type: application/json
Body
{
  "amount": 1000,
  "redirectUrl": "https://www.widgets.co.nz/cart?order=146",
  "currency": "NZD",
  "description": "Widgets",
  "merchantIdCode": "301234567",
  "orderId": "146",
  "transactionType": "REGULAR",
  "status": "PAYMENT_CREATED",
  "id": "0f0451d5-45ab-492d-beb9-6e06b6735d80"
}

Query a Session
GET/openjs/v1/session/{id}

This method can be used to check the details of an existing Session, for example, the status of the payment flow. To make this query the API Client must supply the Session ID with the request.

This is an optional step in the open.js payment flow.

The Session resource will have one of the following states.

State Description Terminal State Next States
SESSION_CREATED A session containing the details of a Consumer’s intent to pay has been created in open.js. N PAYMENT_CREATED
PAYMENT_CREATED Payment has been created and sent to the bank for processing. N PAYMENT_PROCESSED
PAYMENT_PROCESSED Transaction has been completed. Query the payment to get the transaction outcome. Y N/a
URI Parameters
HideShow
id
string (required) Example: 0f0451d5-45ab-492d-beb9-6e06b6735d80

The id of the Session resource (UUID format).


GET https://apitest.paymark.nz/openjs/v1/payment?sessionId=0f0451d5-45ab-492d-beb9-6e06b6735d80
Requestswith body
Headers
Accept: application/json
X-Parent-Referer: https://www.widgets.co.nz
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7920feba-3ef3-457c-9655-59dd12e1d201",
  "payerId": "0215551234",
  "bankId": "ASB",
  "transaction": {
    "amount": 1000,
    "currency": "NZD",
    "order": {
      "id": "146",
      "description": "Widgets"
    }
  },
  "metadata": {
    "userIpAddress": "127.0.0.1",
    "userAgent": "PostmanRuntime/7.20.1"
  },
  "creationTime": "2020-01-16T18:54:49.454Z",
  "modificationTime": "2020-01-16T18:55:00.663Z",
  "status": "AUTHORISED"
}

Retrieve open.js Payment
GET/openjs/v1/payment?sessionId={id}

This method can be used to check the details of an existing payment, inlcuding the payment status. To make this query the API Client must supply the Session ID with the request.

This is the third step in the open.js payment flow.

Refer to the Payment Status Codes section to see a list of payment statuses.

URI Parameters
HideShow
id
string (required) Example: 0f0451d5-45ab-492d-beb9-6e06b6735d80

The id of the Session resource (UUID format).


Online EFTPOS Payment

An Online EFTPOS payment represents a request for a Consumer (bank account holder) to transfer funds to a Merchant.

This method is used by Merchants who manage their own payment page. For Merchants using the Paymark managed payment form refer to open.js payments.

API client must be either a:

  • Registered Merchant with permissions to process payments via this API or,

  • CSP with a contract with a registered Merchant to process transactions on their behalf.

If the API client does not have processing rights for any features documented below, the request will fail.

API client must provide a valid OAuth token with their request.

POST https://apitest.paymark.nz/transaction/oepayment/
Requestswith body
Headers
Content-Type: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "merchantUrl": "https://www.widgets.co.nz/",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "REGULAR",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "userIpAddress": "192.168.0.1"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
"links": [
  {
        "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
        "rel": "self"
    }
  ]
  "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
  "status": "SUBMITTED",
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "REGULAR"
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145"                
  },
  "creationTime": "2016-01-01T11:59:59Z",
  "modificationTime": "2016-01-01T12:01:13Z"
}

Create a Regular Payment
POST/transaction/oepayment/

A regular payment triggers a request to the Consumer’s mobile banking app to authorise the transaction. The transaction type for a regular payment is “REGULAR”. The response indicates whether the request could successfully be made, but does not indicate the outcome, as this is an asynchronous payment method. A callback will be sent when the payment request has been actioned via the Consumer’s mobile banking app.

Required Fields

These fields must be provided in requests.

Name Valid Methods Required for POST
id GET No
payerId POST Yes
bankId POST Yes
payerIdType POST Yes
merchantIdCode POST Yes
merchantUrl POST No
callbackUrl POST Yes
amount POST Yes
transactionType POST Yes
currency POST No
description POST No
orderId POST Yes
userAgent POST Yes
userIpAddress POST Yes

Notes on orderId:

  • This is used on the Consumer’s bank statement and will be truncated at 12 characters. We recommend a maximum of 12 characters is used in this field.

  • This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.

  • The only special characters permitted are: - (hyphen) and space.

Notes on description:

  • This is merchant’s internal description of the payment. This is 100 character field but we recommend a maximum of 20 characters is used in this field.

  • The only special characters permitted are: - (hyphen) and space.


Autopay Payment

The Autopay (Trusted Payment) feature is currently only available to ASB customers. Merchants should first contact Paymark on oe@paymark.co.nz to discuss whether they are eligible for Autopay.

Autopay is a feature that gives eligible Merchants the option to send payment requests to the Bank for authorisation without the need for the Consumer to manually approve the payment in their mobile banking app. The first time a Consumer makes an Online EFTPOS payment, a Merchant can ask for permission to process Autopay payments in the future. The Consumer can then approve Autopay via their mobile banking app at the time they approve the first payment.

Once a Consumer has approved a Merchant for Autopay, the Merchant is able to submit Autopay payments for future purchases the Consumer initiates.

POST https://apitest.paymark.nz/transaction/oepayment/
RequestsAutopay payment setupSubsequent Autopay payment
Headers
Content-Type: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "merchantUrl": "https://www.widgets.co.nz/",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",
    "transactionType": "TRUSTSETUP",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2)   AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "userIpAddress": "192.168.0.1"
  }
}
Responses200200
Body
{
"links": [
  {
        "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
        "rel": "self"
    }
  ]
  "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
  "status": "SUBMITTED",
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "TRUSTSETUP",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",
 },
 "trust": {
     "id": "<uuid>",
     "trustPaymentStatus": "PENDING"

 },
  "creationTime": "2016-01-01T11:59:59Z",
  "modificationTime": "2016-01-01T12:01:13Z"
}
Body
{
    "links": [
      {
            "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
            "rel": "self"
        }
      ],
      "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
      "status": "AUTHORISED",
      "bank": {
        "payerId": "0215551234",
        "bankId": "ASB",
        "payerIdType": "MOBILE"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
      },
      "transaction": {
        "amount": 1000,
        "currency": "NZD",
        "description": "Widgets",
        "orderId": "145",
        "transactionType": "TRUSTED"
      },
      "trust": {
         "id": "<uuid>"
         "trustPaymentStatus": "APPROVED"
        },
      "creationTime": "2016-01-01T11:59:59Z",
      "modificationTime": "2016-01-01T12:01:13Z"
    }
Headers
Content-Type: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "merchantUrl": "https://www.widgets.co.nz/",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "TRUSTED",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",                
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "userIpAddress": "192.168.0.1"
  },

}
Responses200200
Body
{
"links": [
  {
        "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
        "rel": "self"
    }
  ]
  "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
  "status": "SUBMITTED",
  "bank": {
    "payerId": "0215551234",
    "bankId": "ASB",
    "payerIdType": "MOBILE"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "TRUSTSETUP",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",
 },
 "trust": {
     "id": "<uuid>",
     "trustPaymentStatus": "PENDING"

 },
  "creationTime": "2016-01-01T11:59:59Z",
  "modificationTime": "2016-01-01T12:01:13Z"
}
Body
{
    "links": [
      {
            "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
            "rel": "self"
        }
      ],
      "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
      "status": "AUTHORISED",
      "bank": {
        "payerId": "0215551234",
        "bankId": "ASB",
        "payerIdType": "MOBILE"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
      },
      "transaction": {
        "amount": 1000,
        "currency": "NZD",
        "description": "Widgets",
        "orderId": "145",
        "transactionType": "TRUSTED"
      },
      "trust": {
         "id": "<uuid>"
         "trustPaymentStatus": "APPROVED"
        },
      "creationTime": "2016-01-01T11:59:59Z",
      "modificationTime": "2016-01-01T12:01:13Z"
    }

Create an Autopay Payment
POST/transaction/oepayment/

Setting up Autopay via initial payment request

The Merchant needs the Consumer’s consent to set up Autopay; this is done as part of an initial payment transaction. In the payment request transaction type is “TRUSTSETUP”. All other parameters should be the same as a regular payment transaction.

When the request is processed by the Bank, the Bank will prompt the Consumer to approve the payment and set up Autopay. The Consumer will be prompted future transactions can go through without Consumer’s manual approval.

After the Consumer has approved the payment and Autopay setup, the trust (Autopay) status will be sent back in the callback along with the transaction result.

Please note, if you have multiple Merchant accounts under the same parent account, the Autopay creation and maintenance will be at the parent account level and apply to all Merchant accounts in the hierarchy. For example, if you have multiple coffee shops under the same brand, Autopay will be enabled/updated/deleted for all coffee shops at once, not on an individual basis.

Please also familiarise yourself with the Autopay merchant web site requirements.

Subsequent Autopay payments

In subsequent Autopay payment requests, pass in the required information in the payment request together with the “TRUSTED” transaction type. Subsequent Autopay payment requests will be processed immediately without any prompt for the Consumer’s manual approval. The transaction result will be returned with the response, together with the trust (Autopay) status at the time of the payment being processed.

Consumer deleting an Autopay arrangement from the Merchant’s web site

At any time, Consumers can choose to delete an active Autopay arrangement from the merchant’s web site. When this happens, the Merchant must notify Paymark to delete the Autopay arrangement using the Delete Autopay via Merchant request. Paymark will in turn notify the Bank of the deletion.

Consumer deleting an Autopay arrangement from the mobile banking app

At any time, Consumers can choose delete an active Autopay arrangement from their mobile banking app. When this happens, the Bank sends a callback to Paymark to notify of the deletion. Paymark will in turn send a callback to the Merchant to notify the of deletion via Autopay Maintenance Callback.


GET https://apitest.paymark.nz/oemerchanttrust/381a08c8-9189-4995-b07b-6c3821f70e35
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Body
{
    "links": [{
        "href": "<host>/oemerchanttrust/<id>",
        "rel": "self"
    }],
    "id": "<uuid>",
    "payerId": "<string>",
    "payerIdType": "<string>",
    "bankId": "<string>",
    "merchantIdCode": "<integer>",
    "bank": { "id": <uuid>,
              "bankToken": "<string>",
              "status": "<string>",
            },
    "creationTime": "<string>",
    "modificationTime": "<string>"
}

Query Autopay Details
GET/oemerchanttrust/{id}

Merchants use this API to query a particular Autopay arrangement’s details.

URI Parameters
HideShow
id
string (required) Example: 381a08c8-9189-4995-b07b-6c3821f70e35

The UUID of the Autopay resource.


PUT https://apitest.paymark.nz/oemerchanttrust/381a08c8-9189-4995-b07b-6c3821f70e35
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "status": "CANCELLED"
}
Responses200
Body
{
  "links": [
    {
      "href": "<host>/oemerchanttrust/<id>",
      "rel": "self"
    }
  ],
  "id": "<uuid>",
  "payerId": "<string>",
  "payerIdType": "<enum>",
  "bankId": "<enum>",
  "merchantIdCode": "<integer>",
  "bank": {
    "id": "<uuid>",
    "status": "<enum>"
  },
  "creationTime": "<time>",
  "modificationTime": "<time>"
}

Delete Autopay Arrangement
PUT/oemerchanttrust/{id}

Merchants use this API when the Consumer has deleted an Autopay arrangement.

Required Fields

These fields must be provided in requests.

Name Valid Methods Required for PUT
status PUT Yes (should be CANCELLED)
URI Parameters
HideShow
id
string (required) Example: 381a08c8-9189-4995-b07b-6c3821f70e35

The UUID of the Autopay resource.


Query Payment

GET https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
  "links": [
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
      "rel": "self"
    }
  ],
  "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
  "status": "AUTHORISED",
  "bank": {
    "payerId": "0215551234",
    "payerIdType": "MOBILE",
    "bankId": "ASB"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "merchantUrl": "https://www.widgets.co.nz",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "REGULAR",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "145",
    "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US)",
    "userIpAddress": "127.0.0.1",
    "actualSettlementDate": "2016-01-02T11:05:16Z"
  },
  "creationTime": "2016-01-01T11:59:59Z",
  "modificationTime": "2016-01-02T11:05:16Z"
}

Retrieve Individual Payment
GET/transaction/oepayment/{id}

Query an existing OEPayment resource. This method can be used to check the status of a previously submitted regular Online EFTPOS Payment or an Autopay payment request.

To make this query, the API client must supply the UUID (id) of the resource with the request.

URI Parameters
HideShow
id
string (required) Example: 381a08c8-9189-4995-b07b-6c3821f70e35

The UUID of the payment resource.


GET https://apitest.paymark.nz/transaction/oepayment/?orderId=145&merchantIdCode=301234567&payerId=0215551234&fromCreationTime=2016-01-01T11:59:59Z&toCreationTime=2016-01-17T11:59:59Z&fromActualSettlementDate=2016-01-02T00:00:00Z&toActualSettlementDate=2016-01-17T23:59:59Z&status=AUTHORISED&offset=0fe3085c-1f8a-4830-b587-f778d0f5340a&limit=2
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
  "links": [
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/?payerId=0215551234&offset=0fe3085c-1f8a-4830-b587-f778d0f5340a&limit=2",
      "rel": "self",
      "title": "List of OEPayment resources"
    },
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35",
      "rel": "381a08c8-9189-4995-b07b-6c3821f70e35"
    },
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/947a08c8-3856-4995-b07b-3x9384f70e35",
      "rel": "947a08c8-3856-4995-b07b-3x9384f70e35"
    },
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/?payerId=0215551234&offset=618800a4-376a-4ee1-8e56-4a64efcb27b4&limit=2",
      "rel": "prev"
    },
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/?payerId=0215551234&offset=36510f43-eae6-40ab-86b7-9e4e98636137&limit=2",
      "rel": "next"
    }
  ],
  "payments": [
    {
      "id": "381a08c8-9189-4995-b07b-6c3821f70e35",
      "status": "AUTHORISED",
      "bank": {
        "payerId": "0215551234",
        "payerIdType": "MOBILE",
        "bankId": "ASB"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "merchantUrl": "https://www.widgets.co.nz",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
      },
      "transaction": {
        "amount": 1000,
        "transactionType": "REGULAR",
        "currency": "NZD",
        "description": "Widgets",
        "orderId": "145",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US)",
        "userIpAddress": "127.0.0.1",
        "actualSettlementDate": "2016-01-02T11:05:16Z"
      },
      "creationTime": "2016-01-01T11:59:59Z",
      "modificationTime": "2016-01-02T11:05:16Z"
    },
    {
      "id": "947a08c8-3856-4995-b07b-3x9384f70e35",
      "status": "AUTHORISED",
      "bank": {
        "payerId": "0215551234",
        "payerIdType": "MOBILE",
        "bankId": "ASB"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "merchantUrl": "https://www.widgets.co.nz",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=987"
      },
      "transaction": {
        "amount": 5000,
        "transactionType": "REGULAR",
        "currency": "NZD",
        "description": "Big Widget",
        "orderId": "987",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US)",
        "userIpAddress": "127.0.0.1",
        "actualSettlementDate": "2016-01-17T11:06:32Z"
      },
      "creationTime": "2016-01-16T12:01:59Z",
      "modificationTime": "2016-01-17T11:06:32Z"
    }
  ]
}

Retrieve Multiple Payments
GET/transaction/oepayment/{?orderId,merchantIdCode,payerId,fromCreationTime,toCreationTime,fromActualSettlementDate,toActualSettlementDate,status,offset,limit}

Multiple payments can be queried, and specific information on each payment can be retrieved. The default sort order is descending (newest to oldest).

The results of the query are paginated (see also HATEOAS and Pagination).

The following parameters are used to control pagination:

  • offset – first item on the page

  • limit – number of items per page

The following query parameters are supported to retrieve an array of payments:

  • merchantIdCode (required)

  • orderId

  • payerId

  • fromCreationTime and toCreationTime

  • fromActualSettlementDate and toActualSettlementDate

  • status

To return specific information only, the “fields” parameter can be used. For example, to return only the payment status, use fields=status.

For fields that contain sub fields, each sub field must be specified individually. For example, to return the payment amount and user’s IP address, which are sub fields of the transaction field, use fields=transaction.amount,transaction.userIpAddress.

URI Parameters
HideShow
merchantIdCode
string (required) Example: 301234567
orderId
string (optional) Example: 145
payerId
string (optional) Example: 0215551234
fromCreationTime
string (optional) Example: 2016-01-01T11:59:59Z
toCreationTime
string (optional) Example: 2016-01-17T11:59:59Z
fromActualSettlementDate
string (optional) Example: 2016-01-02T00:00:00Z
toActualSettlementDate
string (optional) Example: 2016-01-17T23:59:59Z
status
string (optional) Example: AUTHORISED
offset
string (optional) Example: 0fe3085c-1f8a-4830-b587-f778d0f5340a
limit
string (optional) Example: 2

Online EFTPOS Refund

An Online EFTPOS refund represents a request to transfer funds from a Merchant into a Consumer’s bank account, to refund a previously approved payment.

Refunds can only occur when referring to a previous oepayment resource, that is, unlinked refunds are not possible.

API client must be either a:

  • Registered Merchant with permissions to process payments via this API or,

  • CSP with a contract with a registered Merchant to process transactions on their behalf.

If the API client does not have processing rights, the request will fail.

API client must provide a valid OAuth token with their request.

For refunds, a Merchant’s account must be in good standing, and business rules will apply (as below).

Per Transaction Refund Limit

The maximum amount that may be refunded on a specific payment is:

  • Payment value minus

  • Value of any refunds with the status UNSUBMITTED or REFUNDED against that payment

Refund requests higher than this amount will be rejected.

For example:

  • Original payment $100

  • Partial refund for $50 has been successful (has a REFUNDED status).

  • Partial refund for $30 exists with an UNSUBMITTED status (no response has been received from the Bank)

  • Maximum amount currently available for refund is $20.

  • A (further) refund request for $30 would be rejected.

Overall Refund Limit

In addition to the per transaction limit, the maximum amount that may be refunded at any point in time is the Merchant’s current settlement position.

The current settlement position is:

  • Total unsettled authorised payments minus

  • Total unsettled authorised refunds minus

  • Total UNSUBMITTED refunds

Authorised payments have the status AUTHORISED or REFUNDED. Authorised refunds have the status REFUNDED. Unsettled transactions have no actualSettlementDate.

The settlement position changes throughout the day as the Merchant receives payments and makes refunds.

For example:

  • At 1700, Merchant has received $100 worth of payments today that are due to settle tonight. Merchant has done no refunds today. Current settlement position is $100. Merchant may do up to $100 worth of refunds at this time.

  • Merchant attempts a $150 refund; this is rejected with an error (see error 402 in Validation Errors).

  • At 1730, Merchant receives a $50 payment. Current settlement position is $150. Merchant may now do the $150 refund.

POST https://apitest.paymark.nz/transaction/oerefund/
Requestswith body
Headers
Content-Type: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "merchant": {
    "merchantIdCode": "301234567"
  },
  "transaction": {
    "refundAmount": 1000,
    "refundReason": "Defective goods",
    "refundId": "R145",
    "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "userIpAddress": "192.168.0.1"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
    "links": [
        {
            "href": "https://apitest.paymark.nz/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66",
            "rel": "self"
        }
    ]
       "id": "3c6682fd-4532-499c-b9fc-890943e82a66",
    "status": "REFUNDED",
    "bank": {
        "payerId": "0215551234",
        "bankId": "ASB"
    },
    "merchant": {
        "merchantIdCode": "301234567"
    },
    "transaction": {
        "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
        "refundAmount": 1000,
        "refundReason": "Defective goods",
        "refundId": "R145",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
        "userIpAddress": "192.168.0.1"
    },
    "creationTime": "2016-01-02T11:59:59Z",
    "modificationTime": "2016-01-02T12:00:01Z"
}

Create Refund
POST/transaction/oerefund/

Create a new request, which triggers a request to return funds to the bank account that provided the funds for a previous successful oepayment request.

The response indicates whether the refund succeeded or not; this is a synchronous method, in contrast with oepayment resource creation.

Required Fields

These fields must be provided in requests.

Name Valid Methods Required for POST
id GET No
merchantIdCode POST Yes
refundAmount POST Yes
refundReason POST No
refundId POST Yes
originalPaymentId POST Yes
userAgent POST Yes
userIpAddress POST Yes

Notes on refundId:

  • This is used on the Consumer’s bank statement and will be truncated at 12 characters. We recommend a maximum of 12 characters is used in this field.

  • This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.

  • The only special characters permitted are: - (hyphen) and space.


GET https://apitest.paymark.nz/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
    "links": [
        {
            "href": "https://apitest.paymark.nz/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66",
            "rel": "self"
        }
    ]
    "id": "3c6682fd-4532-499c-b9fc-890943e82a66",
    "status": "REFUNDED",
    "bank": {
        "payerId": "0215551234",
        "bankId": "ASB"
    },
    "merchant": {
        "merchantIdCode": "301234567",
        "merchantUrl": "https://www.widgets.co.nz"
    },
    "transaction": {
        "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
        "refundAmount": 1000,
        "currency": "NZD",
        "refundReason": "Defective goods",
        "refundId": "R145",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
        "userIpAddress": "192.168.0.1",
        "actualSettlementDate": "2016-01-02T12:00:01Z"
    },
    "creationTime": "2016-01-02T11:59:59Z",
    "modificationTime": "2016-01-02T12:00:01Z"
}

Retrieve Individual Refund
GET/transaction/oerefund/{id}

Query an existing oerefund resource. This method can be used to check the status of a previously submitted oerefund request.

To make this query, the API client must supply the UUID (id) of the resource with the request.

URI Parameters
HideShow
id
string (required) Example: 3c6682fd-4532-499c-b9fc-890943e82a66

The UUID of the refund resource


GET https://apitest.paymark.nz/transaction/oerefund/?refundId=R145&merchantIdCode=301234567&payerId=0215551234&fromCreationTime=2016-01-01T11:59:59Z&toCreationTime=2016-01-17T11:59:59Z&status=REFUNDED&fromActualSettlementDate=2016-01-02T00:00:00Z&toActualSettlementDate=2016-01-18T23:59:59Z&originalPaymentId=381a08c8-9189-4995-b07b-6c3821f70e35&bankId=ASB&offset=0bd97e86-b597-4335-a120-15b1cf34a8a0&limit=2
Requestswith body
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
    "links": [
        { "href": "https://apitest.paymark.nz/transaction/oerefund/?payerId=0215551234&offset=0bd97e86-b597-4335-a120-15b1cf34a8a0&limit=2",
        "rel": "self",
        "title": "List of OERefund resources"
        },
        { "href": "https://apitest.paymark.nz/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66",
          "rel": "3c6682fd-4532-499c-b9fc-890943e82a66"
        },
        { "href": "https://apitest.paymark.nz/transaction/oerefund/9f3u08c8-0386-8395-b07b-3x9384f70e9d",
          "rel": "9f3u08c8-0386-8395-b07b-3x9384f70e9d"
        },
        { "href": "https://apitest.paymark.nz/transaction/oerefund/?payerId=0215551234&offset=e7424c00-15ab-4ead-a822-4199e6b38dab&limit=2",
          "rel": "prev"
        },
        { "href": "https://apitest.paymark.nz/transaction/oerefund/?payerId=0215551234&offset=b89bb5ee-05ff-45a0-8bdd-df6c97d65559&limit=2",
          "rel": "next"
        }
    ],
    "refunds": [
        {
            "id": "3c6682fd-4532-499c-b9fc-890943e82a66",
            "status": "REFUNDED",
            "bank": {
                "payerId": "0215551234",
                "bankId": "ASB"
            },
            "merchant": {
                "merchantIdCode": "301234567",
                "merchantUrl": "https://www.widgets.co.nz"
            },
            "transaction": {
                "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
                "refundAmount": 1000,
                "currency": "NZD",
                "refundReason": "Defective goods",
                "refundId": "R145",
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
                "userIpAddress": "192.168.0.1",
                "actualSettlementDate": "2016-01-02T12:00:01Z"
            },
            "creationTime": "2016-01-02T11:59:59Z",
            "modificationTime": "2016-01-02T12:00:01Z"
        }
        {
            "id": "9f3u08c8-0386-8395-b07b-3x9384f70e9d",
            "status": "REFUNDED",
            "bank": {
                "payerId": "0215551234",
                "bankId": "ASB"
            },
            "merchant": {
                "merchantIdCode": "301234567",
                "merchantUrl": "https://www.widgets.co.nz"
            },
            "transaction": {
                "originalPaymentId": "947a08c8-3856-4995-b07b-3x9384f70e35",
                "refundAmount": 5000,
                "currency": "NZD",
                "refundReason": "More defective goods",
                "refundId": "R987",
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
                "userIpAddress": "192.168.0.1",
                "actualSettlementDate": "2016-01-18T11:09:23Z"
            },
            "creationTime": "2016-01-17T11:59:59Z",
            "modificationTime": "2016-01-18T11:09:23Z"
        }
    ]
}

Retrieve Multiple Refunds
GET/transaction/oerefund/{?refundId,merchantIdCode,payerId,fromCreationTime,toCreationTime,status,fromActualSettlementDate,toActualSettlementDate,originalPaymentId,bankId,offset,limit}

Multiple refunds can be queried, and specific information on each refund can be retrieved. The default sort order is descending (newest to oldest).

The results of the query are paginated (see also HATEOAS and Pagination).

The following parameters are used to control pagination:

  • offset – first item on the page

  • limit – number of items per page

The following query parameters are supported to retrieve an array of refunds:

  • refundId

  • merchantIdCode

  • payerId

  • fromCreationTime and toCreationTime

  • status

  • fromActualSettlementDate and toActualSettlementDate

  • originalPaymentId

  • bankId

To return specific information only, the “fields” parameter can be used. For example, to return only the refund status, use fields=status.

For fields that contain sub fields, each sub field must be specified individually. For example, to return the refund amount and user’s IP address, which are sub fields of the transaction field, use fields=transaction.refundAmount,transaction.userIpAddress.

URI Parameters
HideShow
refundId
string (optional) Example: R145
merchantIdCode
string (optional) Example: 301234567
payerId
string (optional) Example: 0215551234
fromCreationTime
string (optional) Example: 2016-01-01T11:59:59Z
toCreationTime
string (optional) Example: 2016-01-17T11:59:59Z
status
string (optional) Example: REFUNDED
fromActualSettlementDate
string (optional) Example: 2016-01-02T00:00:00Z
toActualSettlementDate
string (optional) Example: 2016-01-18T23:59:59Z
originalPaymentId
string (optional) Example: 381a08c8-9189-4995-b07b-6c3821f70e35
bankId
string (optional) Example: ASB
offset
string (optional) Example: 0bd97e86-b597-4335-a120-15b1cf34a8a0
limit
string (optional) Example: 2

Callback

Payment Callback

The callback is used to notify the API client about the transaction status of a payment or Autopay set up request. For security and reliability reasons, Merchants are recommended to ensure the transaction ID in the callback matches that sent in response to the original payment request. The Merchant may also choose to retrieve and validate the transaction results using the Retrieve Individual Payment method and not rely on the return post variables received in the callback.

A callback is always provided for a payment request, unless the transaction status in the response to the initial payment request is one of ERROR, DECLINED or EXPIRED.

The callback is usually provided as soon as the Consumer has actioned the payment request (maximum four minutes). In the event of a transmission issue this callback may be provided at a later time. Note: In the event a duplicate callback is provided, the second or subsequent callback should be ignored.

If a callback URL has been specified in the payment request this is used. Else the default callback URL configured when the Merchant was set up is used.

The API client will receive a POST request to the callback URL with the following parameters:

Field Description
merchantOrderId orderId sent with the original payment request.
status Refer to OEPayment section in Status Codes.
transactionId Transaction ID of the payment.
oeTrustStatus Autopay status, either ACTIVE or CANCELLED. Only contains a value when the transaction type sent with the payment was TRUSTSETUP.
oeTrustId Unique identifier for the Autopay arrangement. Only contains a value when the transaction type sent with the payment was TRUSTSETUP.
signature Base64 encoded digital signature of the above fields. For a regular payment these fields are merchantOrderId, status and transactionId. When setting up an Autopay arrangement these fields are merchantOrderId, status, transactionId, oeTrustStatus and oeTrustId. The Merchant should decode the signature using the public key and verify the contents of the merchantOrderId, status, transactionId, oeTrustStatus and oeTrustId fields received in the callback message are the same as these fields from the decoded signature. If these are different, the Merchant should query transaction details.

Example of callback request and subsequent decoding:

http://localhost:9000/callback?merchantOrderId=OE%20test&status=AUTHORISED&transactionId=31d5b6aa-4c99-4bbd-b81a-186fc2a88fed&signature=IhDkJg9geuZoeRrrcv0YLFwfGThjGGHwDxWekXniqPp8e8yCYSXHHpSLLdNhvcrUfCL4tY6YV%2FRuq5NHNOOeVCggPISfbgYoOCM6PCxglLNB7QlgadGTl8b2Teiz2Sg%2B2qJWm8hwX9oOg%2FeCwm0K6t7RvZjIEh6n%2F9JYtaOoTpy6ntRdArVECOYgnNHV%2BD22oczcvQxqON5qpd6zPFMfd%2FXZWJtG9QPmsbdd0HscRiCxPSwfFoCgc887tKRm%2B1SsyZj%2B8Eczk436Y2Lp47pp3nk93hX6GKIA7dq7ydbzTcdua4PSaEMdB%2F86EcM4K%2BEWb906uslrXgFkUIRUudfePQhdO9Qjgk%2F82kL9IZicjnK4kIZMp2tkJC%2FFoyW1Vl61bCQlIHQhFCDtQnU1UwVZH4IwcgYRSqoMKaMCMevMGnAISylhKJ1VTyHfiGIRHuP7a4QsiXHrHBKl1oxdcP6rIFbOckJShp5hpnejXuuXg0UzXp%2F6uGL9E9ewxJKD5xrvkcA5RQD1uJhvozuMJDxYzlaHlZW%2BzBxZg1rtx2ZgocFkQuh1MQNzXEJE0BSV3CYpDsXuCzgofLYj5%2FmbZ1QqvcBEOq4y3GJhOt5CgmWSv%2FudfPfpa6eOJ8gWEdHFF7rZ7wHEAif8XqSLgHPnOfAo3%2FtlVvTxJAG0ZnBH%2FgrStdk%3D
var app = require('express')();
var Promise = require('promise');
var crypto = require('crypto');
var SIGNING_ALGORITHM = "RSA-SHA512";
var verifySignedHash = function(signedMessage, originalMessage) {
    return new Promise(function(resolve, reject) {
        console.log("signedMessage:"+signedMessage);
        var verifier = crypto.createVerify(SIGNING_ALGORITHM);
        verifier.update(new Buffer(originalMessage, 'utf8'));
        var result = verifier.verify(process.env.PUBLIC_KEY_STRING, signedMessage, 'base64');
        console.log("VERIFY: " + result);
        resolve(result);
    });
};
app.post('/callback', function(req, res){
    var merchantOrderId = req.query.merchantOrderId;
    var status = req.query.status;
    var transactionId = req.query.transactionId;
    var signature = req.query.signature;
    var oeTrustStatus = req.query.oeTrustStatus;
    var oeTrustId = req.query.oeTrustId;
    var originalMessage = "merchantOrderId="+merchantOrderId+"&status="+status+"&transactionId="+transactionId;
    //Add oeTrustStatus="+oeTrustStatus+"&oeTrustId="+oeTrustId if transactionType is TRUSTSETUP
    verifySignedHash(signature, originalMessage)
        .then(function(matches) {
            if(matches) {
                res.status(200).send();
            } else {
                res.status(401).send();
            }
        })
        .catch(function(error) {
            console.log("Error", error);
            res.status(400).send();
    });
});
var server = app.listen(process.env.PORT || 9000, function(){
    console.log('Listening on port %d', server.address().port);
});

Important: The callback URL is recommended to return a 200 OK status code in case of success. The status code is ignored and Paymark does no further processing if the callback URL returns an error. In this event the API client must query the transaction to get the status.

Refund

For refunds, a response is usually provided immediately. However if there is a transmission issue, and a response is not provided, the API client needs to query the refund status until a terminal status is reached. Refer to GET section in Online EFTPOS Refund and Refund section in Status Codes.

If the response is not returned immediately the Merchant should not attempt the same refund again: the refund status should be queried.

Autopay Maintenance Callback

At any time, Consumers can choose delete an active Autopay arrangement from their mobile banking app. When this happens, the Bank sends a callback to Paymark to notify of the deletion. Paymark will in turn send a callback to the Merchant to notify the deletion. The Merchant should then delete their Autopay record for this Customer.

Note: The default callback URL configured when the Merchant was set up is used as the Autopay Maintenance Callback URL.

The Merchant will receive a POST request to the default callback URL with the following parameters:

Field Description
oeTrustStatus Autopay status, either ACTIVE or CANCELLED.
oeTrustId Unique identifier for the Autopay arrangement.
signature Base64 encoded digital signature of returned fields: oeTrustId=<UUID>&oeTrustStatus=<status>.

Field Glossary

Payment and Refund Transactions

The following table details the fields used in payment and refund transactions.

Field Type Format Description
id String “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Paymark-generated universally unique identifier (UUID) for the resource.
payerId String Refer to Merchant Web Site Requirements section for payerId validation that is enforced by the API. Consumer’s personal identifier (mobile phone number for ASB, mobile number for Heartland Bank, mobile phone number or customer ID for The Co-operative Bank, mobile phone number, Westpac1Id (Customer ID) or Westpac username for Westpac).
bankId String Fixed values Consumer Bank to which the payment request is to be sent. Refer to payerIdType and Bank Mapping for supported Consumer Banks.
payerIdType String Fixed values Defines the type of payerId that has been used. Note: Each bank allows different types. Refer to payerIdType and Bank Mapping.
merchantId String “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Paymark-provided universally unique identifier (UUID) for a Merchant.
merchantIdCode String “30XXXXXXX” Paymark-provided human friendly identifier for a Merchant. If a CSP is processing the transaction on the Merchant’s behalf, the Merchant’s unique merchantIdCode needs to be used in the request.
merchantUrl String URL format Location of Merchant’s web site. The URL must start with http:// or https:// and contain at least one / after the domain name, for example, https://www.widgets.co.nz/ or https://www.widgets.co.nz/shop/specials. Allowed characters: alphanumeric, colon, hyphen, forward slash, equals, question mark, ampersand, dot.
callbackUrl String URL format including any query string parameters and values Where Merchant wishes to receive notifications relating to this payment request. If no callback URL is included in the request, the default callback URL configured when the Merchant was set up is used. The URL must start with http:// or https:// and contain at least one / after the domain name, for example, https://www.widgets.co.nz/ or https://www.widgets.co.nz/callback?order=145. Allowed characters: alphanumeric, colon, hyphen, forward slash, equals, question mark, ampersand, dot.
amount Integer Numeric characters only (no decimal point) Financial amount of transaction, in smallest units of currency i.e. cents for NZD. E.g. $83.25 is represented as 8325, $10.00 is represented as 1000.
currency String [A-Z]{3} ISO-4217 (alpha-3) currency code. Defaults to NZD.
description String Up to 100 characters (recommend 20 characters max) Merchant’s internal description of the payment. The only special characters permitted are: -,. and space.
orderId String Up to 100 characters (recommend 12 characters max) Merchant order reference for the Consumer. This will be truncated at 12 characters on the Consumer’s bank statement. Note: This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.
userAgent String Up to 8192 bytes Browser user agent detected by Merchant web server.
userIpAddress String IPv4 address in dot notation, or IPv6 in colon notation Browser’s IP address detected by Merchant web server.
status String Fixed values See relevant resource’s section in Status Codes.
creationTime Timestamp YYYY-MM-DDTHH:mm:ssZ Date and time that Paymark resource was created.
modificationTime Timestamp YYYY-MM-DDTHH:mm:ssZ Last date and time that Paymark resource was modified.
refundId String Up to 100 characters (recommend 12 characters max) Merchant refund reference for the Consumer. This will be truncated at 12 characters on the Consumer’s bank statement. Note: This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.
refundAmount Integer Numeric Amount to refund to Consumer’s bank account.
refundReason String Up to 512 characters Merchant’s internal description of the refund.
originalPaymentId String “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” UUID of the original payment that is being refunded; used to validate refundAmount.

payerIdType and bankId Mapping

Supported Consumer Banks are:

  • ASB (bankId = ASB)

  • Heartland Bank (bankId = HEARTLAND)

  • The Co-operative Bank (bankId = COOPERATIVE)

  • Westpac (bankId = WESTPAC)

All Consumer Banks support MOBILE (mobile phone number) as the payerIdType. This is the recommended payerIdType. Refer to the User Payment Experience section for information on validating the mobile number.

The Co-operative Bank (bankId = COOPERATIVE) and Westpac (bankId = WESTPAC) also support CUSTOMERID (a reference specific to these banks). Refer to the User Payment Experience section for the various ways this reference should be validated for each bank.

Status Codes

Payment Status Codes

Valid values for the status field of an oepayment resource. These are set by Paymark, and cannot be modified by the API client.

Status Description Next Statuses
NEW A new payment request from a Merchant, which has not been processed yet. SUBMITTED, ERROR
SUBMITTED A payment request that has been sent to a Bank for processing, and for which the Bank has acknowledged the request. AUTHORISED, DECLINED, EXPIRED
AUTHORISED Bank has notified Paymark that the Consumer (account holder) has authorised the payment. REFUNDED
DECLINED Bank has notified Paymark that the payment has been declined, either by the Consumer (account holder) or the Bank itself. C.f. Sandbox for decline scenarios. We recommend the Merchant now offers the Consumer the opportunity to attempt another payment. Terminal
EXPIRED Bank has notified Paymark that the expiry timeout has been passed. We recommend the Merchant now offers the Consumer the opportunity to attempt another payment. Terminal
REFUNDED A payment request that was successfully authorised, and has now been successfully refunded (partially or in full). REFUNDED
ERROR A payment request could not be successfully sent to the Bank. Terminal

Refund Status Codes

Valid values for the status field of an oerefund resource. These are set by Paymark, and cannot be modified by the API client.

Status Description Next Statuses
UNSUBMITTED Refund request created but not yet received by the Bank; could occur if Bank becomes unavailable. REFUNDED, DECLINED, ERROR
REFUNDED Bank has responded to refund request with a success code. Terminal
DECLINED Bank declined refund request, for example, due to insufficient funds, or other business logic. Terminal
ERROR Bank responded to refund request with a system error. Terminal

Errors

Error Handling

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.

If reconciliation is necessary, and if you want to confirm the result of a previous API request, you should issue a GET to the appropriate endpoint to query the resource status.

Validation Errors

Below are example error message responses and formats. These responses are provided synchronously.

Generic 400 Error

{ “error”: “validation” }

This could be returned in any of the following cases:

  • The data passed in was not in the 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 additional validation such as:

  • String too long.

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

If this is the case, the error response contains more information to help the API client debug the situation.

{ “error”: “validation”, “messages”: [ { “field”: “payerId”, “message”: “invalid format ‘abc’” }, { “field”: “bankId”, “message”: “field required” }, { “field”: “abc”, “message”: “unknown field” }, { “field”: “id”, “message”: “cannot update field” } ] }

Unauthorized – 401

{ “error”: “invalid access token” }

Payment Required – 402

Merchant has requested a refund for an amount greater than the current settlement position. See also Overall Refund Limit.

{ “error”: “Refund amount exceeds your current balance. Please try again later.” }

Forbidden - 403

{ “error”: “forbidden” }

Not Found - 404

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

Method Not Allowed - 405

{ “error”: “UnsupportedMediaType”, “reference”: "" }

Not Acceptable - 406

{ “error”: “Unsupported Accept Format” }

Conflict Error - 409

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 API client last retrieved it. This is done via the modificationTime field.

  • Attempting to set up an Autopay arrangement with a Bank / Payer ID / Merchant combination that already exists.

    {
      "error": "conflict",
      "messages": [
      {
        "field": "Status",
        "message": "Conflicting field"
        }
      ]
    }

Unsupported Media Type – 415

{ “error”: “UnsupportedMediaType”, “reference”: "" }

Too Many Requests – 429

Thrown when the maximum transactions per second threshold has been reached; the API client should retry this transaction.

{ “error”: “TooManyRequests” }

Server Error - 5xx

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

A reference uuid is given back to the API client so it can be quoted back to Paymark to get more information. The reference is logged alongside the exception in the logs.

{ “error”: “Service Unavailable”, “reference”: "" }

HATEOAS and Pagination

HATEOAS

HATEOAS (Hypertext As The Engine Of Application State) links are included as part of the JSON response body.

The link types that can be returned are:

  • self link: a link to the current request.

  • resource instance links: links to the resource instances are included when doing a search of OEPayment or OERefund. A resource link is included for each displayed search result.

  • next / prev links: next and previous links in paginated resources. If there is another page of search results, a next link is included to navigate to the next page of search results. The prev link is used to navigate to the previous page of search results.

Pagination

Searching on OEPayment and OERefund paginates search results. There are two query parameters used to control pagination:

  • offset: the ID of the first result to return. If no offset is specified, the first page is returned.

  • limit: the number of items to return per page. The default value is 5.

Search results are ordered by creationTime then id. Specifying id as offset will return a page of results starting from the item with the given id.

The HATEOAS next and prev links are used to navigate between the pages of search results.

Sandbox

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

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

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

Integrators can create a Sandbox account here.

C.f. Endpoints and Authentication sections.

ASB Transactions

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

Payment Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount over $2 (200c) Consumer has authorised the payment. Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
117c Payment has been declined. Consumer response
137c Payment has been declined and response has been delayed, Sandbox response is received after 6 minutes. Consumer response

Expired Scenarios

Transaction Amount Response Description Response Type
120c Consumer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Consumer response
130c Consumer did not action the payment request within four minutes and response has been delayed, Sandbox response is received after 6 minutes. (Lack of) Consumer response

Error Scenarios

Transaction Amount Response Description Response Type
139c Error occurred (refer to Paymark) and response has been delayed, Sandbox response is received after 6 minutes. System response
140c Error occurred (refer to Paymark). System response

Refund Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount over $2 (200c) Refund has been successfully processed. System response

Declined Scenarios

Transaction Amount Response Description Response Type
106c Payment not found. System response

Expired Scenarios

The expired scenario does not apply to refunds as these require no Consumer action.

Error Scenarios

Transaction Amount Response Description Response Type
114c Refund transaction failed. System response

Heartland Bank Transactions

The following responses can be simulated for Heartland Bank transactions (bankId = HEARTLAND).

Payment Request

Authorised Scenarios

Transaction Amount Response Description Response Type
130c ($1.30) Consumer has authorised the payment. Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
131c Payment has been declined and response has been delayed, Sandbox response may be received up to 10 minutes after the transaction was initiated. Consumer response

Expired Scenarios

Transaction Amount Response Description Response Type
132c Consumer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Consumer response

Error Scenarios

Transaction Amount Response Description Response Type
116c Paymark system issue (refer to Paymark). System response

Refund Request

Authorised Scenarios

Transaction Amount Response Description Response Type
130c ($1.30) Refund has been successfully processed. System response

Declined Scenarios

Declined scenarios are not available in the Online EFTPOS Sandbox for Heartland Bank transactions.

Expired Scenarios

The expired scenario does not apply to refunds as these require no Consumer action.

Error Scenarios

Transaction Amount Response Description Response Type
106c Paymark system issue (refer to Paymark). System response

The Co-operative Bank Transactions

The following responses can be simulated for The Co-operative Bank transactions (bankId = COOPERATIVE).

Payment Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount over $1.20 (120c) Consumer has authorised the payment. Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
117c Payment has been declined. Consumer response

Expired Scenarios

Transaction Amount Response Description Response Type
118c Consumer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Consumer response

Error Scenarios

Transaction Amount Response Description Response Type
104c Paymark system issue (refer to Paymark). System response

Refund Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount over $1.20 (120c) Refund has been successfully processed. System response

Declined Scenarios

Transaction Amount Response Description Response Type
102c Bank has declined the transaction for some reason. System response

Expired Scenarios

The expired scenario does not apply to refunds as these require no Consumer action.

Error Scenarios

Transaction Amount Response Description Response Type
104c Paymark system issue (refer to Paymark). System response

Westpac Transactions

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

Payment Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount under $1 (100c) or over $1.20 (120c) Consumer has authorised the payment. Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
117c Payment has been declined by the Consumer. Consumer response

Expired Scenarios

Expired scenarios are not available in the Online EFTPOS Sandbox for Westpac transactions.

Error Scenarios

Transaction Amount Response Description Response Type
108c System error. System response

Refund Request

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount under $1 (100c) or over $1.20 (120c) Refund has been successfully processed. System response

Declined Scenarios

Declined scenarios are not available in the Online EFTPOS Sandbox for Westpac transactions.

Expired Scenarios

The expired scenario does not apply to refunds as these require no Consumer action.

Error Scenarios

Transaction Amount Response Description Response Type
108c Paymark system issue (refer to Paymark). System response

Sandbox Public Key

The public signing key for the Sandbox environment is shown below.

-----BEGIN PUBLIC KEY-----

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAt+npTQm8TRnwc0UO+E7w
+DnxqSPZy7BjON1pQr50vxraGwDkGT9OM3MWmBfPzfJBGq4zw7gbQkjPowwCsPSw
fjmSE9GIvm3LnmFq3chFaDYLW9QdyVTnUQh1MV7yPC2e/rc8apemZaYQYHhEqSjy
dh/G/bZYJyV11+jw/WIyx4f0UujUZa3cR4DyD/VomSuYnUzJVSPaKG126bqvfJCt
32ueopYmIWxTNw+6IaP4Uo+h8jZoFUqF0gFsQYmnh5ZoGpNO9tXkkbSK+fNLcyPw
FTejjGSTOharroQJoqZby0zGUV3v7dDAq79rRL7t2weMcnCWwzlmxOkgv39Hjlme
1sfqpANi1X7b5RnWx+b47NMtyOpkaJecWS+nOpiKbSCGgKpN/a1FiYzCC3vrbN0M
0wIeDNjQ97uM9nh7YyGeTniZ9jO5O4hoSmGs/1ih08YzEf141g3kqFJqsONz7bmL
eyTrhTw1QU4x9K3y9GM19y9CZ3QOPbCQEHGkFnJMvwJNDqsCeHOtz2V3F+KSGpse
B2cTDgC5iL5TdBgleAxiuvCefmjQLGIk5i84MuxxEataYWakrLhWZ9VX6adpiqYe
jHGLniT10ksfmpy1/Mkedup9/cu4Gk4+qaL9/IQZRi+R2nRkVfT9CuBlaeF96Oae
6dwjanI4GvQFdVFm3lmXQkUCAwEAAQ==

-----END PUBLIC KEY-----

Merchant Web Site Requirements

The Merchant’s web site needs to comply with the following requirements for the presentation and handling of the Online EFTPOS payment method.

General Requirements

The Merchant’s web site needs to be SSL to be able to transact. The Merchant needs to use the public key (shown in Message Signature) to authenticate callback messages from Paymark.

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

User Payment Experience

Please contact Paymark on oe@paymark.co.nz to request a copy of the Online EFTPOS user experience guidelines. These guidelines include how to present the bank selector, validation error presentation and call to action screens.

An explanation of what Online EFTPOS is must be included. For example, mouse over help text. The copy for this is: "To learn more about making a successful Online EFTPOS transaction click here".

The payerId must be validated for general correctness, for example, correct number of digits.

Mobile number validation rules are:

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

  • 023, 024, 025, 026 not allowed.

  • Minimum 9 digits, maximum 11 digits.

  • Only numeric characters allowed.

Examples (not exhaustive!):

Allowed:

  • 021012345

  • 0221234567

Not allowed:

  • 021-012-345

  • +64 22 123 4567

  • 026123456

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

You may give the Consumer an option to save the payerID for use on their next purchase.

You may also offer CUSTOMERID as a payerId for The Co-operative Bank and Westpac. CUSTOMERID validation rules differ for each bank. If you plan to offer CUSTOMERID as a payerId please contact Paymark on oe@paymark.co.nz to discuss required validation.

Transaction Result

The actual transaction response will be returned to the Merchant in the callback (refer to Payment information in Status Codes).

The web site must display only “approved” or “not approved” to the Consumer. A “not approved” response may be displayed as soon as the Merchant receives this.

“Not approved” includes the Consumer actively declining the transaction, an error such as an invalid payerID, the payment request expiring, or any other scenario that does not result in an AUTHORISED payment status. Refer to the Sandbox section for details of these cases.

When the payment is “not approved” the copy to display is: "Payment failed. To learn more about making a successful Online EFTPOS transaction click here".

In the event the Merchant does not receive a callback after 5 minutes, the Merchant must query the payment status from Paymark. If a terminal transaction result is not available at this time, the web site must display “Sorry, this transaction could not be processed at this time.”

The Merchant may also choose to poll for a transaction response before this time using a binary backoff algorithm. Additional details are available from Paymark if needed.

Autopay

Online EFTPOS Autopay is available to eligible Merchants. Please contact Paymark on oe@paymark.co.nz if you wish to discuss Online EFTPOS Autopay.

Before you set up Autopay there are a number of prerequisites you need to consider. You can see the details here.

Revision History

This section describes the changes to this API specification.

Date Change
2 December 2016 First publication.
14 December 2016 Updated permitted special characters and Sandbox values.
23 December 2016 Corrected headers, updated endpoint examples to use Sandbox endpoint.
16 January 2017 Updated bearer token information, added transaction ID in callback, removed API version.
26 January 2017 Updated callback signature.
22 March 2017 Added support for Co-operative Bank.
20 April 2017 Added Co-op simulator.
26 April 2017 Added ability to view settlement date when retrieving a payment.
10 May 2017 Added ability to view settlement date when retrieving a refund.
19 May 2017 Added ability to query payments and refunds by settlement date.
2 Feb 2018 Added draft content for trusted merchant functionality.
4 April 2018 Added draft content for Westpac integration.
7 May 2019 Updated content for Westpac integration and trusted payment section.
18 September 2019 Added Heartland Bank content and general maintenance.
4 December 2019 Updated create refund section.
5 December 2019 Corrected callback section.
6 December 2019 Streamlined sandbox section.
11 March 2020 Added open.js payments information.

Generated by aglio on 12 May 2020