Online EFTPOS API

An Introduction

This guide will get you up and running to add Online EFTPOS payments to your web site. Online EFTPOS gives your customers payment choice and you payment security. And you can even keep your existing card payments gateway.

Please read this API specification thoroughly. This helps you understand the overall flow of an Online EFTPOS payment, and see the options to integrate. This is especially useful if you have never used Online EFTPOS.

Online EFTPOS sends a payment request to your customer’s bank app simply using their phone number. You do not need any bank credentials to request payment. Your customer approves the payment in their bank app using bank grade security. This level of security is why Online EFTPOS has no chargebacks.

And refunds are done in real time: as soon as you request the refund your customer has this money back in their bank account.

Online EFTPOS is already supported on these online shopping platforms:

  • Appropo

  • Book N Order

  • Blackpepper

  • EstarOnline

  • Magento

  • Mobi2Go

  • WooCommerce

Contact your platform integrator or developer to find out more. Or contact us on oe@paymark.co.nz and we can put you in touch with an integrator.

And if you manage your own platform you can easily add an Online EFTPOS payment form into your checkout page.

Best of all regardless of how you take card payments (and even if you don’t take card payments online) you can still accept Online EFTPOS payments. This is great for Kiwis starting out in business. And for established businesses wanting to keep their current card payments provider but still offer their customers choice.

If you want one solution to offer card payments, including Google Pay, and secure bank account payments (Online EFTPOS), we recommend our sister eCommerce gateway, Click.

If you use Shopify as an eCommerce platform, regardless of the payment methods you want to offer, we recommend the Click Shopify plug in. You can then select whether to offer card payments, including Google Pay, and secure bank account payments (Online EFTPOS) through this plug in, or Online EFTPOS only.

Payment Flow

Online EFTPOS is an asynchronous payment flow as your customer needs to approve the payment.

You initiate a payment request. Your customer selects their bank and enters their mobile number. Your customer then approves the payment in their bank app, and your web site is notified of the payment outcome. Once approved, the payment is irrevocable. Your bank account is then credited during the overnight settlement process.

Refund Flow

Online EFTPOS refunds are synchronous as your customer does not need to approve the refund.

You initiate a refund, the bank approves this and moves the money back into your customer’s account immediately, and the Online EFTPOS API responds with the outcome. Your account is then debited during the overnight settlement process.

Useful Information

You need an Online EFTPOS account with Paymark to accept Online EFTPOS payments.

Set up a Sandbox account to use while building your integration.

Set up a Production account when you are ready to go live.

You will receive different API credentials for each account. These only work for that account e.g. you cannot use your Sandbox credentials for a live payment.

There are different signatures for each environment (Sandbox and Production). See Message Signature section for details.

Online EFTPOS is a server to server API, that is, the customer’s web browser sends a request to your web server and your web server then sends the request to the Online EFTPOS API.

Getting Started

Before You Start

So you get started on the right path, run through this checklist before starting your integration build.

  1. Create a Sandbox account.

  2. Read this API specification thoroughly.

  3. Familiarise yourself with the web site requirements section.

  4. Familiarise yourself with the integration test script and go live checklist. These form part of the Paymark certification of your integration.

  5. Try out Online EFTPOS for yourself! Or if your bank does not offer you Online EFTPOS, check out the video instead.

Build Your Integration

These are the major steps in building your integration.

  1. Create the bearer token call.

  2. Add the OPEN plugin to your checkout / payment page.

  3. Build the refund functionality into your website admin tool.

  4. Handle all transaction outcomes (as per Sandbox section).

  5. Run through the integration test script and ensure you have passed all the test cases.

  6. Ensure your web site meets the web site requirements.

When You Finish

Once your integration is ready to release we need you to complete the go live checklist below.

  1. Provide us with a test site that we can use to certify your integration.

  2. Provide us with a support contact point.

For merchant developers, you are now ready to create a production account.

For platform integrators or developers, there are some additional requirements as below.

  1. Provide us with a link to your web site where you will publish information about your Online EFTPOS integration. We will review this and provide feedback.

  2. Provide us with any plug in code or support material you will provide with your integration. We will review this and provide feedback.

  3. Confirm your team knows how to contact Paymark if you have any issues.

  4. Update your internal / sales processes to include steps needed for your customers to create an Online EFTPOS Merchant account with Paymark, and to configure their web site with their Paymark account details so they can start accepting Online EFTPOS payments.

  5. You can now market your integration to customers as being Paymark certified and we will include your integration in this Online EFTPOS API specification.

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 web site will accept.

The Authorization header is used to authenticate and authorise requests to the Online EFTPOS API.

Versioning

You should expect the Online EFTPOS API to 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 Sandbox endpoints is https://apitest.paymark.nz/. This URL is used in response examples in this specification. This environment is used for API development.

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

The endpoints available are:

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

  • /openjs/v1/session to create a session and allow you to load the Online EFTPOS payment form.

  • /openjs/v1/payment to retrieve payment details immediately after a session has been created, including processing status.

  • /transaction/oepayment to retrieve payment details at any time.

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

  • /oemerchanttrust to search and manage Autopay arrangements.

For example, the full URL for the Sandbox session endpoint is https://apitest.paymark.nz/openjs/v1/session.

For example, the full URL for the Production session endpoint is https://api.paymark.nz/openjs/v1/session.

Security

Paymark requires that all connections are encrypted with TLS; there are no unencrypted endpoints available. You 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 create an Online EFTPOS account to get a Consumer Key and Consumer Secret (API credentials). You must keep these credentials secure.

Different credentials will be provided for each environment (Sandbox and Production).

Refer to this section for details on creating an Online EFTPOS account.

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 from Paymark will be signed so that you can verify 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:

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

The public signing key for the Production environment is:

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

API Methods

This section describes the methods that may be used to create and manage Online EFTPOS transactions. This includes:

OPEN Plugin

The OPEN plugin is the JavaScript framework that allows you to build payment flows that support various Open Payments Platform (OPEN) integrations.

The plugin enables Online EFTPOS payments and is the first OPEN integration.

The plugin handles the creation of the Online EFTPOS payment form and manages the transaction flow. The plugin also supports Autopay for Autopay enabled Merchants (see also Autopay payment.)

The Online EFTPOS payment form displays the payment amount and manages bank and payer ID details. The web site displaying this form needs to specify the business (merchant) that the customer is buying from. See also web site requirements.

Getting Started

Configuration: You need to enter all the domains of your web sites where the OPEN plugin will be used into the OpenJS Configuration area under Settings in the Online EFTPOS Portal.

Processing a transaction: an OPEN plugin payment flow consists of the following steps:

  1. Create a session and receive a session ID.
  2. Use the session ID to load the payment form on your web site.
  3. Query the session status to confirm when the transaction has been completed.
  4. Query the payment status to get the transaction outcome.

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 plugin payment flow.

The package exposes openjs.init(), openjs.initModal() and openjs.openModal() functions, and 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 Online EFTPOS payment form.

<script type="text/javascript" src="https://open.demo.paymark.co.nz/v1"></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>

Calling openjs.initModal() and openjs.openModal() will do the following:

  • Create a modal with 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.

  • openjs.initModal() is a trigger for the modal to open.

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

<script type="text/javascript" src="https://open.demo.paymark.co.nz/v1"></script>
<script>
    const urlParams = new URLSearchParams(window.location.search)
    const sessionId = urlParams.get('sessionId')
    if (window.openjs) {
        window.openjs.initModal({ sessionId })
    }
    document.getElementById('pay-button').onclick = function(e) {
        window.openjs.openModal({ sessionId })
        e.preventDefault();
    }
</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
RequestsRegular paymentAutopay payment
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"
}
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",
  "status": "SESSION_CREATED",
  "id": "67cd570a-2d16-451c-943e-67ede8be5b3d"
}
Headers
Accept: application/json
Content-Type: application/json
Authorization: Bearer access_token
Body
{
  "amount": 1000,
  "redirectUrl": "https://www.widgets.co.nz/cart?order=147",
  "currency": "NZD",
  "description": "Widgets",
  "merchantIdCode": "301234567",
  "orderId": "147",
  "allowAutopay": "true",
  "trustIds": [
    "180928f1-61cf-49ef-8e36-55b725fd256c",
    "42995abc-87b5-4370-95f7-eb8f41be88ab"
  ]
}
Responses201
Headers
Content-Type: application/json
Body
{
  "amount": 1000,
  "redirectUrl": "https://www.widgets.co.nz/cart?order=147",
  "currency": "NZD",
  "description": "Widgets",
  "merchantIdCode": "301234567",
  "orderId": "147",
  "status": "SESSION_CREATED",
  "id": "67cd570a-2d16-451c-943e-67ede8be5b3d",
  "allowAutopay": "true",
  "trustIds": [
    "180928f1-61cf-49ef-8e36-55b725fd256c",
    "42995abc-87b5-4370-95f7-eb8f41be88ab"
  ]
}

Create a Session
POST/openjs/v1/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. You also indicate whether the customer wants to use Autopay. The response will be a session ID that you can use to load the Online EFTPOS payment form on your web site.

The session request is a server to server request and includes your Online EFTPOS account details and payment amount. This model is used to ensure the information received from the payment form loaded on your 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 plugin payment flow.

Available Fields

These fields may be used in requests.

Name Type Required Notes
amount integer Y Must be a positive amount. Amount is in cents.
redirectUrl string N Must be https, no port numbers allowed. Underscores are permitted in the resource path only (not the domain name). If provided, the customer 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 N Your 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 shown on the customer’s bank statement and will be truncated at 12 characters. We recommend you use only 12 characters in this field. The orderId does not need to be unique, however we recommend it is unique to facilitate transaction tracking.
Allowed characters: /^[ A-Za-z0-9\-]*$/
allowAutopay boolean N Valid values: “false”, “true”. False must be used for a guest (unauthenticated) checkout. True may be used for a logged in customer when you want to offer the customer the option to set up Autopay.
trustIds array (string) N ID/s of existing Autopay arrangements this logged in customer has with you.

GET https://apitest.paymark.nz/openjs/v1/session/67cd570a-2d16-451c-943e-67ede8be5b3d
RequestsRegular paymentAutopay payment
Headers
Accept: application/json
Authorization: Bearer access_token
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",
  "status": "PAYMENT_CREATED",
  "id": "67cd570a-2d16-451c-943e-67ede8be5b3d",
  "allowAutopay": "false"
}
Headers
Accept: application/json
Authorization: Bearer access_token
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",
  "status": "PAYMENT_CREATED",
  "id": "67cd570a-2d16-451c-943e-67ede8be5b3d",
  "allowAutopay": "true",
  "trusts": [
    {
      "id": "180928f1-61cf-49ef-8e36-55b725fd256c",
      "bankId": "ASB",
      "payerId": "021980655"
    },
    {
      "id": "42995abc-87b5-4370-95f7-eb8f41be88ab",
      "bankId": "ASB",
      "payerId": "0215551234"
    }
  ]
}

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

This method is used to check the details of an existing session, for example, the status of the payment flow. The session ID must be provided with the request.

This is the third step in the OPEN plugin 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 customer’s intent to pay has been created 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: 67cd570a-2d16-451c-943e-67ede8be5b3d

The id of the Session resource (UUID format).


GET https://apitest.paymark.nz/openjs/v1/payment?sessionId=67cd570a-2d16-451c-943e-67ede8be5b3d
RequestsReduced contentRegular paymentAutopay payment
Headers
Accept: application/json
X-Parent-Referer: "https://www.widgets.co.nz"
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7920feba-3ef3-457c-9655-59dd12e1d201",
  "bankId": "ASB",
  "status": "AUTHORISED"
}
Headers
Accept: application/json
Authorization: Bearer access_token
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36
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"
}
Headers
Accept: application/json
Authorization: Bearer access_token
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "348f4f58-c9cc-4660-8095-d9a3175a035a",
  "payerId": "021980655",
  "bankId": "ASB",
  "transaction": {
    "amount": 1000,
    "currency": "NZD",
    "order": {
      "id": "147",
      "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",
  "trustId": "180928f1-61cf-49ef-8e36-55b725fd256c"
}

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

This method can be used to check the details of an existing payment, including the payment status, within one hour of the session being created. The session ID must be provided with the request.

This is the fourth step in the OPEN plugin payment flow.

The reduced content response is returned when the your web site queries the transaction outcome. The regular payment and autopay payment responses, which contain sensitive data, are provided in a server to server request.

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

URI Parameters
HideShow
id
string (required) Example: 67cd570a-2d16-451c-943e-67ede8be5b3d

The id of the Session resource (UUID format).


Query Payment

GET https://apitest.paymark.nz/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35
RequestsSingle paymentAutopay payment
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
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"
}
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Responses200
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
  "links": [
    {
      "href": "https://apitest.paymark.nz/transaction/oepayment/348f4f58-c9cc-4660-8095-d9a3175a035a",
      "rel": "self"
    }
  ],
  "id": "348f4f58-c9cc-4660-8095-d9a3175a035a",
  "status": "AUTHORISED",
  "bank": {
    "payerId": "021980655",
    "payerIdType": "MOBILE",
    "bankId": "ASB"
  },
  "merchant": {
    "merchantIdCode": "301234567",
    "merchantUrl": "https://www.widgets.co.nz",
    "callbackUrl": "https://www.widgets.co.nz/callback?order=147"
  },
  "transaction": {
    "amount": 1000,
    "transactionType": "TRUSTSETUP",
    "currency": "NZD",
    "description": "Widgets",
    "orderId": "147",
    "userAgent": "PostmanRuntime/7.20.1",
    "userIpAddress": "127.0.0.1",
    "actualSettlementDate": "2020-01-17T11:30:45.154Z"
  },
  "trust": {
    "id": "180928f1-61cf-49ef-8e36-55b725fd256c",
    "trustPaymentStatus": "APPROVED"
  },
  "creationTime": "2020-01-16T18:54:49.454Z",
  "modificationTime": "2020-01-16T18:55:00.663Z"
}

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

This method can be used to check the status of a previously submitted payment request. In contrast to the finite life OPEN plugin retrieve payment request, this method can be used at any time. The payment ID must be provided 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
RequestsMultiple payments
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

Online EFTPOS refunds are real time: as soon as the refund is approved funds are returned to the customer’s bank account. The merchant’s bank account is then debited in overnight settlement.

Refunds must be linked to an approved payment. The maximum amount that can be refunded is the approved payment amount. Partial refunds are possible.

There are some business rules that apply to refunds: a per transaction limit and an overall merchant limit.

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 Merchant Refund Limit

In addition to the per transaction limit, the maximum amount that may be refunded at any point in time is your 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.

Your settlement position changes throughout the day as you receive payments and process refunds.

For example:

  • At 10:00am you have received $100 worth of payments that are due to settle tonight. You have not processed any refunds today. Your current settlement position is $100. You may process up to $100 worth of refunds at this time.

  • You attempt to fully refund a $150 payment (process a $150 refund). This will be rejected with an error (see error 402 in Validation Errors).

  • Half an hour later, at 10:30am, you receive a $50 payment. Your current settlement position is now $150. You can now process the $150 refund.

POST https://apitest.paymark.nz/transaction/oerefund/
RequestsCreate refund
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 a 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 approved Online EFTPOS payment.

The response indicates whether the refund succeeded or not. This is a synchronous method.

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 shown on the customer’s bank statement and will be truncated at 12 characters. We recommend you use only 12 characters in this field.

  • The refundId does not need to be unique, however we recommend it is unique to facilitate transaction tracking.

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


GET https://apitest.paymark.nz/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66
RequestsSingle refund
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 Single Refund
GET/transaction/oerefund/{id}

This method can be used to check the status of a previously submitted refund request. The refund ID must be provided 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
RequestsMultiple refunds
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

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 payment or refund search. 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 for multiple payments or refunds 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. The maximum permitted value is 2147483646.

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.

Autopay Maintenance

Autopay is available to ASB customers and qualifying businesses (merchants). You need to first contact Paymark on oe@paymark.co.nz to discuss whether you 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 customer to manually approve the payment in their bank app. The first time a customer makes an Online EFTPOS payment, a merchant can ask for permission to process Autopay payments in the future. The customer can then approve Autopay via their bank app at the time they approve the first payment.

Once a customer has approved a merchant for Autopay, the merchant is able to submit Autopay payments for future purchases the customer initiates. C.f. including trustIds in an OPEN plugin session request.

At any time, customers can choose to delete an active Autopay arrangement from your web site. When this happens, you 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.

Autopay Maintenance Callback

Customers can delete an active Autopay arrangement from their bank app. When this happens the bank sends a callback to Paymark to notify of the deletion. Paymark will in turn send a callback to you to notify the deletion. You should then delete your Autopay record for this customer.

Note: The default callback URL configured when your account was created is used as the Autopay Maintenance Callback URL.

You 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>.
GET https://apitest.paymark.nz/oemerchanttrust/180928f1-61cf-49ef-8e36-55b725fd256c
RequestsAutopay arrangement
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/oemerchanttrust/180928f1-61cf-49ef-8e36-55b725fd256c",
        "rel": "self"
    }],
    "id": "180928f1-61cf-49ef-8e36-55b725fd256c",
    "payerId": "021980655",
    "payerIdType": "MOBILE",
    "bankId": "ASB",
    "merchantIdCode": "301234567",
    "bank": { "id": c20a99d7-f236-4219-9841-0e0cfba9b8df,
              "status": "ACTIVE"
            },
    "creationTime": "2020-01-16T18:54:49.454Z",
    "modificationTime": "2020-01-16T18:55:00.663Z"
}

Retrieve Autopay Details
GET/oemerchanttrust/{id}

The method is used to query a particular Autopay arrangement’s details. The trust ID must be provided with the request.

URI Parameters
HideShow
id
string (required) Example: 180928f1-61cf-49ef-8e36-55b725fd256c

The UUID of the Autopay resource.


PUT https://apitest.paymark.nz/oemerchanttrust/180928f1-61cf-49ef-8e36-55b725fd256c
RequestsDelete Autopay
Headers
Accept: application/vnd.paymark_api+json
Authorization: Bearer access_token
Body
{
  "status": "CANCELLED"
}
Responses200
Headers
Content-Type: application/vnd.paymark_api+json;version=1.1
Body
{
    "links": [{
        "href": "https://apitest.paymark.nz/oemerchanttrust/180928f1-61cf-49ef-8e36-55b725fd256c",
        "rel": "self"
    }],
    "id": "180928f1-61cf-49ef-8e36-55b725fd256c",
    "payerId": "021980655",
    "payerIdType": "MOBILE",
    "bankId": "ASB",
    "merchantIdCode": "301234567",
    "bank": { "id": c20a99d7-f236-4219-9841-0e0cfba9b8df,
              "status": "CANCELLED"
            },
    "creationTime": "2020-01-16T18:54:49.454Z",
    "modificationTime": "2020-04-20T14:23:01.663Z"
}

Delete Autopay Arrangement
PUT/oemerchanttrust/{id}

You use this request when the customer has opted to delete an Autopay arrangement from your web site. The trust ID must be provided with the request.

Required Fields

These fields must be provided in requests.

Name Valid Methods Required for PUT
status PUT Yes (is always CANCELLED)
URI Parameters
HideShow
id
string (required) Example: 180928f1-61cf-49ef-8e36-55b725fd256c

The UUID of the Autopay resource.


Field Glossary

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

Field Type Format Description
actualSettlementDate Timestamp YYYY-MM-DDTHH:mm:ssZ Date and time that this transaction was settled.
amount Integer Numeric characters only (no decimal point) Financial amount of payment 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.
bankId String Fixed values Bank to which the payment request is to be sent.
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.
creationTime Timestamp YYYY-MM-DDTHH:mm:ssZ Date and time that Paymark resource was created.
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. Allowed characters: alphanumeric, hyphen, comma, full stop and space.
id String “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” Paymark-generated universally unique identifier (UUID) for the resource.
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 Merchant’s web site. The URL must start with http:// or https:// and contain at least one / after the domain name e.g. https://www.widgets.co.nz/ or https://www.widgets.co.nz/shop/specials. Allowed characters: alphanumeric, colon, hyphen, forward slash, equals, question mark, ampersand, full stop.
modificationTime Timestamp YYYY-MM-DDTHH:mm:ssZ Last date and time that Paymark resource was modified.
orderId String Up to 100 characters (recommend 12 characters max) Merchant order reference for the Customer. This will be truncated at 12 characters on the Customer’s bank statement. Note: This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions. Allowed characters: alphanumeric, space, hyphen.
originalPaymentId String “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” UUID of the original payment that is being refunded; used to validate refundAmount.
payerId String Alphanumeric. Customer’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).
payerIdType String Fixed values Defines the type of payerId that has been used. Note: Each bank allows different types.
refundAmount Integer Numeric characters only (no decimal point) Financial amount of refund 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.
refundId String Up to 100 characters (recommend 12 characters max) Merchant refund reference for the Customer. This will be truncated at 12 characters on the Customer’s bank statement. Note: This does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions. Allowed characters: alphanumeric, space, hyphen.
refundReason String Up to 512 characters Merchant’s internal description of the refund.
status String Fixed values See relevant resource’s section in Status Codes.
transactionType String Fixed values “REGULAR”, “TRUSTED” or “TRUSTSETUP” indicating a one off payment, Autopay payment or Autopay set up.
userAgent String Up to 8192 bytes Browser’s user agent detected by Merchant’s web server.
userIpAddress String IPv4 address in dot notation, or IPv6 in colon notation Browser’s IP address detected by Merchant’s web server.

Status Codes

Payment Status Codes

The table below shows the various statuses an Online EFTPOS payment can have. For non terminal payments, the next possible statuses are also shown.

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 Customer (account holder) has authorised the payment. REFUNDED
DECLINED Bank has notified Paymark that the payment has been declined, either by the Customer (account holder) or the Bank itself. C.f. Sandbox for decline scenarios. We recommend the Merchant now offers the Customer 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 Customer 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

The table below shows the various statuses an Online EFTPOS refund can have.

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 notified Paymark that the refund was completed and the Customer has received funds back. Terminal
DECLINED Bank declined the 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 sending a request, 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 transaction.

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

Sandbox

The Sandbox environment can be used to simulate payment and refund operations for each bank (ASB, Heartland Bank, The Co-operative Bank and Westpac). This lets you create payments and refunds before you write a line of code. And you can use the Sandbox to test your code once this is written.

The transaction amount used in the payment or refund request will determine the response that is received. You do not need a bank app or a phone to create transactions. You should be able to handle every response for every bank.

Status updates for “customer 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”.

You 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) Customer has authorised the payment. Customer response

Declined Scenarios

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

Expired Scenarios

Transaction Amount Response Description Response Type
120c Customer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Customer response
130c Customer did not action the payment request within four minutes and response has been delayed, Sandbox response is received after 6 minutes. (Lack of) Customer 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 Customer 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) Customer has authorised the payment. Customer 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. Customer response

Expired Scenarios

Transaction Amount Response Description Response Type
132c Customer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Customer 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 Customer 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) Customer has authorised the payment. Customer response

Declined Scenarios

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

Expired Scenarios

Transaction Amount Response Description Response Type
118c Customer did not action the payment request within four minutes (expiry timeout has been passed). (Lack of) Customer 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 Customer 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) Customer has authorised the payment. Customer response

Declined Scenarios

Transaction Amount Response Description Response Type
117c Payment has been declined by the Customer. Customer 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 Customer action.

Error Scenarios

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

Merchant Web Site Requirements

Online EFTPOS is an asynchronous payment method and this section shows you how your web site needs to handle the payment flow. This section also goes through the Paymark requirements for presenting Online EFTPOS as a payment method that we will check for when we certify your integration.

The payment process should be an enjoyable experience for your customers to minimise abandoned carts. We provide some general guidelines and specific requirements in this API specification for the presentation and handling of the Online EFTPOS payment method.

Check out the Online EFTPOS Ice Cream Shop for a good example of the OPEN plugin in a live environment.

We expect your web site to use New Zealand English spelling and be grammatically correct. We recommend you get a professional proof reader to review your site.

We will also review your integration to ensure you have encouraged a beautiful user experience.

Payment Experience

While the OPEN plugin payment form does the “heavy lifting” when your customer makes an Online EFTPOS payment, your web site needs to present Online EFTPOS elsewhere on your web site in a manner that follows the Paymark standards.

Online EFTPOS needs to be included anywhere on the web site that mentions the payment methods the merchant offers. For example, home page, shopping cart screens, help content.

In text form, Online EFTPOS must be referred to as “Paymark Online EFTPOS”. Alternatively, the Online EFTPOS logo can be used. You may also display the bank logos (for the banks that offer their customers Online EFTPOS). Contact Paymark on oe@paymark.co.nz to get the logo files.

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

When the customer is taken to the page where they select the payment method:

  • For first time use and guest checkout, there should be no default payment method selected.

  • For the second and subsequent use for logged in customers, the last used payment method should be the default selection.

  • Online EFTPOS should be presented as the first payment method option (or second when the merchant also offers card payments).

  • Bank logos need to be shown with the Online EFTPOS payment method option.

  • All payment methods should be visible without scrolling or the need to move around the screen.

Once Online EFTPOS is selected as a payment method for this transaction, the Online EFTPOS payment form must be displayed prominently on the screen, for example, dynamically sized to centre on the screen.

The total amount to be paid and the merchant’s name must also be clearly visible.

Payment Result

The OPEN plugin payment form will display the payment result to the customer and provide a call to action if the payment was unsuccessful.

If you wish to display additional information about the payment, your web site must display only “approved” or “not approved”. “Not approved” includes the customer 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. You must not display any specifics about why the payment was unsuccessful.

If the payment status is still non terminal after five minutes, the web site must display “Sorry, this transaction could not be processed at this time.” You can also prompt the customer to check their bank app to see if their payment is showing in their account. If it is, the customer should not attempt the payment again (to avoid being double charged). There is a clean up process that will update the payment status (you see) to a terminal state.

If the payment result is reflected in the browser tab name ensure this shows the correct result. That is, “Approved” for a payment with an AUTHORISED status and “Not approved” for any other terminal status.

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 prerequisites you need to consider for your web site. You can see the details here.

Security Requirements

Your web site needs to be SSL to be able to transact. You need to use the relevant public key (shown in [Message Signature] (#security-message-signature) to authenticate callback messages from Paymark.

Paymark Certification

Paymark Certification Process

Once your integration has been built, Paymark will certify this and offer suggestions for improvements before you can liven your first Merchant.

Paymark will follow the test script below. We expect you have completed this (and all test cases have passed) before you ask Paymark to certify your integration. This ensures the best possible customer experience and minimises rework for you.

For this certification, we need a sample web site that is connected to the Paymark Online EFTPOS Sandbox. This site needs to have products available for each of the payment values shown in the Sandbox. We will also be reviewing the overall presentation of Online EFTPOS on the web site.

Integrator Test Script

Transaction Test Cases

Each of these transactions can be simulated in the Sandbox by varying the transaction amount. You can select any bank and enter any valid New Zealand mobile number. You do not need the bank app installed to use the Sandbox environment.

  • On Chrome, on a desktop device, make a successful payment for each bank (ASB, Heartland Bank, The Co-operative Bank, Westpac).

  • Refund each of these payments using either your platform’s administration portal (if you have one) or the Online EFTPOS Portal.

  • On Chrome, on a desktop device, make a declined payment for either ASB or Westpac.

  • On Chrome, on a desktop device, make an expired payment for either ASB or The Co-operative Bank.

  • On Chrome, on a desktop device, make an error payment for either ASB or Westpac.

  • On an Android phone, make a successful payment for each bank (ASB, Heartland Bank, The Co-operative Bank, Westpac).

  • On an iPhone, make a successful payment for each bank (ASB, Heartland Bank, The Co-operative Bank, Westpac).

UX Testing

The general appearance of the OPEN plugin on the Merchant’s web site is pleasant, and all the elements mentioned in the Merchant Web Site Requirements section have been included.

Online EFTPOS is shown as the first payment method option (or second only to card payments).

The following browsers and devices have been checked:

  • Chrome (desktop)

  • Edge (desktop)

  • Firefox (desktop)

  • Safari (desktop)

  • Safari (iPad)

  • Safari (iPhone)

  • Chrome (Android)

Setting Up A Production Account

You’ve made it this far and you’re ready to go live!

The starting point for the onboarding process will depend on your company structure.

If you have a simple company structure you can onboard using the online tool. If you need help using this tool, check out the user guide.

A simple company structure is defined as:

  • One online account is needed for the brand (all transactions will settle into the same bank account).

  • Company is registered with the New Zealand Companies Office.

  • People (rather than trusts) own the company.

  • Company owners all have a New Zealand driver’s licence (this information is needed in the online tool).

  • Company has a New Zealand bank account (this information is needed in the online tool).

This will start the process of completing Paymark’s AML requirements. Our Paymark AML Co-ordinator will be in touch with you to complete this process and collect additional information such as NZBN and documentation to confirm your bank account number.

If you do not meet the definition above, we need to collect onboarding information manually and you need to sign a contract. Contact us on oe@paymark.co.nz and our Sales team will get in touch to complete this process.

Once Paymark has completed AML requirements and created your Production Online EFTPOS account you will have access to the Production Online EFTPOS Portal. You can get the (Production) consumer key and secret and merchant ID from this portal.

Support

New Integrations

For help building your integration or creating a new account, please contact us on oe@paymark.co.nz.

We also need a support contact point for you. Send details to oe@paymark.co.nz. We use this for any outage or other notifications. We recommend this is a group rather than an individual.

Existing Customers

If you already have an Online EFTPOS account, please contact our 24/7 Customer Care Help Desk on 0800 PAYMARK or support@paymark.co.nz.

Generated by aglio on 07 May 2021