Online EFTPOS API

Overview

This document describes the Online EFTPOS API.

This API enables CSPs and Merchants to submit payment requests directly to the Consumer’s mobile banking application. 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 APIs.

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

We're in the process of integrating with Westpac Bank and Westpac customers will soon be able to use Online EFTPOS.

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 UAT endpoints is https://apitest.uat.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.

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.

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

For example, the full URL for the UAT oepayment endpoint is https://apitest.uat.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.

From 1 April 2018, Paymark will cease support for TLS 1.0. 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, UAT 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 and refunds, and query payment and refund details.

Online EFTPOS Payment

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

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 perform transactions on its 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/

Create a new request, which triggers a request to the Consumer’s bank mobile app to authorise the transaction. 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 bank mobile 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.


POST https://apitest.paymark.nz/transaction/oepayment/
RequestsTrusted payment setupSubsequent Trusted payments
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 a Trusted Payment
POST/transaction/oepayment/

Trusted Merchant is a new feature that gives 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 banking app. The first time a consumer makes an Online Eftpos payment, a merchant can ask for permission to process Trusted Payments in the future. The consumer can then approve a merchant to make Trusted via their banking app at the time they approve the first payment.

Once a merchant has been approved for Trusted Payments by a consumer, the merchant is able to submit Trusted Payments to be processed immediately without the consumer needing to manually approve each payment in the banking app.

Merchants can be enabled for Trusted Merchant payments upon request.

Setting up Trusted Merchant Transactions via initial payment request

In order to get started, you need to get the consumer’s consent to setup trusted payment as part of making an initial payment transaction. In the payment request, indicate that transaction type is “TRUSTSETUP”, and all other parameters should be the same as a regular transaction.

When the request is processed by the bank, bank will prompt consumer to approve the payment with trust in their banking app, so all future transactions can go through without customer’s manual approval.

After consumer approving and completing the setup, trust status will be sent back in the Payment Callback along with the transaction result.

Subsequent trusted payments

In subsequent trusted payment requests, pass in the same information in the request together with the “TRUSTED” transaction type. Subsequent trusted payment will be processed immediately without any prompt for consumer’s manual approval. Transaction result will be returned within the response, together with the trust status at the time of the payment being processed.

Consumer deleting a trust and the Callback to the Merchant

At any time, consumers can choose delete an active trust from their banking application. In this case, Bank sends a callback to Paymark to notify the deletion. Paymark will in turn call back to the merchant to notify the deletion via Trust Maintenance Callback


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": "SUBMITTED",
  "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": "REGULAR",
    "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 OE Payment or a Trusted OE 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&creationTime=2016-01-01T11:59:59Z&status=SUBMITTED&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": "SUBMITTED",
      "bank": {
        "payerId": "0215551234"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=145"
      },
      "transaction": {
        "amount": 1000,
        "currency": "NZD",
        "description": "Widgets",
        "orderId": "145",
        "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": "SUBMITTED",
      "bank": {
        "payerId": "0215551234"
      },
      "merchant": {
        "merchantIdCode": "301234567",
        "callbackUrl": "https://www.widgets.co.nz/callback?order=987"
      },
      "transaction": {
        "amount": 5000,
        "currency": "NZD",
        "description": "Big Widget",
        "orderId": "987",
        "transactionType": "REGULAR",
        "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,creationTime,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:

  • orderId

  • merchantIdCode

  • payerId

  • creationTime

  • actualSettlementDate

  • 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 subfields, each subfield 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
orderId
string (optional) Example: 145
merchantIdCode
string (optional) Example: 301234567
payerId
string (optional) Example: 0215551234
creationTime
string (optional) Example: 2016-01-01T11:59:59Z
actualSettlementDate
string (optional) Example: 2016-01-02T11:05:16Z
status
string (optional) Example: SUBMITTED
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 perform transactions on its 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. Unsetttled transactions have no actualSettlementDate.

This 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"
    },
    "merchant": {
        "merchantIdCode": "301234567"
    },
    "transaction": {
        "refundAmount": 1000,
        "refundReason": "Defective goods",
        "refundId": "R145",
        "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35"
    },
    "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"
    },
    "merchant": {
        "merchantIdCode": "301234567"
    },
    "transaction": {
        "refundAmount": 1000,
        "refundReason": "Defective goods",
        "refundId": "R145",
        "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
        "actualSettlementDate": "2016-01-03T11:12:01Z"
    },
    "creationTime": "2016-01-02T11:59:59Z",
    "modificationTime": "2016-01-03T11:12: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&creationTime=2016-01-02T11:59:59Z&status=REFUNDED&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"
            },
            "merchant": {
                "merchantIdCode": "301234567"
            },
            "transaction": {
                "refundAmount": 1000,
                "refundReason": "Defective goods",
                "refundId": "R145",
                "originalPaymentId": "381a08c8-9189-4995-b07b-6c3821f70e35",
                "actualSettlementDate": "2016-01-03T11:12:01Z"
            },
            "creationTime": "2016-01-02T11:59:59Z",
            "modificationTime": "2016-01-03T11:12:01Z"
        }
        {
            "id": "9f3u08c8-0386-8395-b07b-3x9384f70e9d",
            "status": "REFUNDED",
            "bank": {
                "payerId": "0215551234",
            },
            "merchant": {
                "merchantIdCode": "301234567",
            },
            "transaction": {
                "refundAmount": 5000,
                "refundReason": "Defective goods",
                "refundId": "R987",
                "originalPaymentId": "947a08c8-3856-4995-b07b-3x9384f70e35",
                "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,creationTime,status,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

  • creationTime

  • status

  • actualSettlementDate

  • originalPaymentId

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 subfields, each subfield 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
creationTime
string (optional) Example: 2016-01-02T11:59:59Z
status
string (optional) Example: REFUNDED
actualSettlementDate
string (optional) Example: 2016-01-03T11:12:01Z
originalPaymentId
string (optional) Example: 381a08c8-9189-4995-b07b-6c3821f70e35
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 trust setup. 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 status of the trust, could be either ACTIVE or CANCELLED. Only contains value when there was a Trust Setup with the payment.
oeTrustId id of the trust. Only contains value when there was a Trust Setup with the payment.
signature Base64 encoded digital signature of returned fields: merchantOrderId=<mOId>&status=<status>&transactionId=<UUID>&oeTrustId=<UUID>&oeTrustStatus=<oeTrustStatus>

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.

Note on refunds:

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

Trust Maintenance Callback

At any time, consumer can choose to delete a previously setup trust from their banking application. When this happens, bank sends a callback to Paymark to update the status of the trust, and Paymark will in turn callback to merchant to update the status of the trust.

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

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

Field Description
merchantIDCode merchantID of the trust.
payerID payerID of the trust.
bankId bankID of the trust.
oeTrustStatus status of the trust, ACTIVE or CANCELLED.
oeTrustId id of the trust.
signature Base64 encoded digital signature of returned fields: merchantId=<mOId>&payerID=<payerID>&bankId=<bankID>&oeTrustId=<UUID>&oeTrustStatus=<oeTrustStatus>

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 [+]{0,1}[0-9]{8,14} Consumer’s personal identifier (mobile phone number for ASB, mobile phone number or customer ID for Co-operative Bank, mobile phone number or Westpac1Id for Westpac Bank). Refer to Merchant Web Site Requirements section for payerId validation that is enforced by the API.
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 website. The URL must contain at least one / after the domain name, for example, https://www.widgets.co.nz/ or https://www.widgets.co.nz/shop/specials.
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 12 characters Merchant’s internal description of the payment.
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)

  • Co-operative Bank (bankId = COOPERATIVE)

  • Westpac Bank (bankId =WESTPAC)

We're in the process of integrating with Westpac Bank and Westpac customers will soon be able to use Online EFTPOS.

Each Consumer Bank can allow different types as the payerIdType. The table below shows what is allowed by each Consumer Bank (as specified in bankId).

Consumer Bank (bankId) Allowed Types (payerIdType)
ASB MOBILE
COOPERATIVE MOBILE, CUSTOMERID
WESTPAC MOBILE, WESTPAC1ID

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. Terminal
EXPIRED Bank has notified Paymark that the expiry timeout has been passed. 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.

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.

    {
      "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, The Co-operative Bank and Westpac). The transaction amount used in the payment or refund request will determine the response that is received.

Refer to the Endpoints and Authentication sections for details.

ASB Transactions

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

Payment Request

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

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
101c Consumer does not have Bank mobile app registered for this payerId (mobile number for ASB). System response
102c Consumer does not have Bank mobile app registered (app not set up for use). System response
103c Consumer has Online EFTPOS disabled (PayHere turned off for ASB). System response
104c Consumer has no default bank account. System response
105c Consumer is over their account limit. System response
118c Invalid trust or incorrect trust details submitted for a trusted payment. System 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

Error Scenarios

Transaction Amount Response Description Response Type
111c Duplicate payment request. System response
112c Paymark system issue (refer to Paymark). System response
113c Paymark system issue (Online EFTPOS disabled for this Bank). System response
115c Payment request formatted incorrectly. System response
116c Paymark system issue (authentication). 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. Bank response

Error Scenarios

Transaction Amount Response Description Response Type
108c Bank system issue. System response
111c Duplicate refund request. System response
112c Paymark system issue (refer to Paymark). System response
113c Paymark system issue (Online EFTPOS disabled for this Bank). System response
115c Payment request formatted incorrectly. System response
116c Paymark system issue (authentication). System response

Note: The expire scenario does not apply to refunds as these require no Consumer action.

The Co-operative Bank (Co-op) Transactions

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

Payment Request

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

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 by the Consumer. Consumer response
102c Bank has declined the transaction for some reason, for example, the Consumer’s account is closed. System 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 An error occurred when the payment request was sent to the Bank. System response

Refund Request

Authorised Scenarios

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

Declined Scenarios

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

Error Scenarios

Transaction Amount Response Description Response Type
104c An error occurred when the refund request was sent to the Bank. System response

Note: The expire scenario does not apply to refunds as these require no Consumer action.

Westpac Transactions

We're in the process of integrating with Westpac Bank and Westpac customers will soon be able to use Online EFTPOS.

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

Payment Request

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

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
101c Consumer does not have Bank mobile app registered for this payerId (mobile number or Westpac1ID). System response
102c Consumer does not have Bank mobile app registered (app not set up for use). System response
103c Consumer has Online EFTPOS disabled. System response
104c Consumer has no default bank account. System response
105c Consumer is over their account limit. System 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

Error Scenarios

Transaction Amount Response Description Response Type
111c Duplicate payment request. System response
115c Payment request formatted incorrectly. 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. Bank response

Error Scenarios

Transaction Amount Response Description Response Type
106c Original Payment is not found. System response
107c The original payment was not successful. System response
108c Bank system issue. System response
111c Duplicate refund request. System response
112c Paymark system issue (refer to Paymark). System response
113c Paymark system issue (Online EFTPOS disabled for this Bank). System response
115c Payment request formatted incorrectly. System response
116c Paymark system issue (authentication). System response

Note: The expire scenario does not apply to refunds as these require no Consumer action.

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.

The Merchant’s web site needs to display an option to explain 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".

Branding Requirements

Please contact Paymark for Online EFTPOS branding requirements.

Create Transaction

A Bank selector must be displayed; the Consumer uses this to select the Bank to send the payment request to: ASB, The Co-operative Bank or Westpac options need to be displayed. As new Consumer Banks come on board this specification will be updated.

Once the Bank has been selected, a prompt must be displayed telling the Consumer what sort of payerId to enter. An example of this payerId needs to be included, showing the Consumer how to format this.

For ASB, this must be the mobile number the Consumer has set up for their ASB mobile banking app. This should be in the format 0210123456.

For The Co-operative Bank, this can be either the Co-op customer ID, or the mobile number the Consumer has set up for their Co-op online banking and banking app. The customer ID should be in the format 1234567. The mobile number should be in the format 0210123456.

For Westpac (coming soon), this can be either the Westpac Banking Application ID (Westpac1ID), or the mobile number the Consumer has set up for their Westpac online banking and banking app. The mobile number should be in the format 0210123456. The Westpac1ID is a 6 digit number 123456.

The payerId must be validated for general correctness, for example, correct number of digits. Paymark will provide copy to display in the event the payerId has failed this validation.

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

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

Customer ID validation rules for The Co-operative Bank are:

  • Exactly 7 digits

  • Begins with 1 - 9

Westpac1ID validation rules for Westpac Bank (Coming soon, subjected to change) are:

  • Exactly 6 digits

  • Begins with 1 - 9

The Merchant may give the Consumer an option to save the bankId and payerId for use on their next purchase.

Transaction Being Processed

These requirements apply when the Consumer has selected a “Pay Now” type option.

A prompt must be shown to tell the Consumer what to do now for the selected bank. Examples of this are shown on the Paymark demonstration site The Ice Cream Shop.

The Merchant may also choose to display:

  • A “processing” type spinner.

  • An order ID for this order (that has been included with the payment request, which the Consumer will see in the mobile app).

  • A timer counting down from 4 minutes (maximum time the Consumer has to action the payment request).

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.

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.

Generated by aglio on 04 Dec 2018