Online EFTPOS v1.1 API Documentation - Amazon S3 · API client must provide a valid OAuth token with their request. POST Create a new request, ... AppleWebKit/537.36 (KHTML, like

Online EFTPOS v1.1 API Documentation

Online EFTPOS v1.1 API Documentation v0.17 2

TABLE OF CONTENTS Overview ................................................................................................................................................. 4

Connections ............................................................................................................................................ 5

Transport ............................................................................................................................................. 5

HTTP Headers .................................................................................................................................... 5

Versioning ........................................................................................................................................... 5

Endpoints ............................................................................................................................................ 6

Errors ................................................................................................................................................... 6

Exception Handling ......................................................................................................................... 6

Security ............................................................................................................................................... 7

Authentication.................................................................................................................................. 7

HTTP Request................................................................................................................................. 8

HTTP Response .............................................................................................................................. 8

Message Signatures ....................................................................................................................... 9

OEPayment ........................................................................................................................................... 10

POST ................................................................................................................................................. 10

HTTP Request............................................................................................................................... 11

HTTP Response ............................................................................................................................ 12

GET ................................................................................................................................................... 13

Individual Payment ........................................................................................................................ 13

Multiple Payments ......................................................................................................................... 15

Required Fields ................................................................................................................................. 19

OERefund.............................................................................................................................................. 20

Per Transaction Refund Limit............................................................................................................ 20

Overall Refund Limit .......................................................................................................................... 21

POST ................................................................................................................................................. 22

HTTP Request............................................................................................................................... 22

HTTP Response ............................................................................................................................ 23

GET ................................................................................................................................................... 24

Individual Refund .......................................................................................................................... 24

Multiple Refunds ........................................................................................................................... 26

Required Fields ................................................................................................................................. 30

Merchant Callback ................................................................................................................................ 31

Field Glossary ....................................................................................................................................... 32

payerIdType and bankId Mapping .................................................................................................... 36

Status Tables ........................................................................................................................................ 37

OEPayment ....................................................................................................................................... 37


OERefund.......................................................................................................................................... 38

Error Messages ..................................................................................................................................... 39

Validation Errors ................................................................................................................................ 39

Generic 400 Error .......................................................................................................................... 39

Unauthorized – 401 ....................................................................................................................... 40

Payment Required – 402 .............................................................................................................. 40

Forbidden – 403 ............................................................................................................................ 40

Not Found – 404 ........................................................................................................................... 40

Method Not Allowed – 405 ............................................................................................................ 41

Conflict Error – 409 ....................................................................................................................... 41

Unsupported Media Type – 415 .................................................................................................... 41

Too Many Requests – 429 ............................................................................................................ 42

Server Error – 5xx ......................................................................................................................... 42

HATEOAS and Pagination .................................................................................................................... 43

HATEOAS ......................................................................................................................................... 43

Pagination ......................................................................................................................................... 43

Sandbox Environment ........................................................................................................................... 44

Payment Request .............................................................................................................................. 44

Refund Request ................................................................................................................................ 45


OVERVIEW This document describes the Online EFTPOS v1.1 API. This API enables CSPs and Merchants to submit payment requests directly to the customers’ mobile banking application. Customer payments can also be partially or completely refunded. For this version, only ASB customers are supported.


CONNECTIONS

TRANSPORT The Online EFTPOS 1.1 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 (detailed in https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html), Paymark requires that you specify the Accept and Authorization headers. The Accept header is used to specify the content type that your API client will accept. Online EFTPOS v1.1 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 Online EFTPOS v1.1.

VERSIONING The API version is prepended to the resource location in the URI. For example:

v1.1 has the prefix /v1.1/

v2.0 would have the prefix /v2/ You should expect that the Online EFTPOS v1.1 API will evolve over time as Paymark adds new features. To ensure compatibility, you must specify the API version with every call you make to the API. At the moment, the latest version of Online EFTPOS v1.1 is 1.1. A particular version of a resource will always retain all defined fields, however additional fields may be added over time. 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/. This URL is used in response examples in this document. The base URL for all Online EFTPOS Sandbox (c.f. Sandbox Environment section) endpoints is https://apitest.paymark.nz/. The endpoints available are:

/bearer for authenticating and obtaining OAuth 2.0 bearer tokens.

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

/v1.1/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/v1.1/transaction/oepayment/. For example, the full URL for the UAT oepayment endpoint is https://apitest.uat.paymark.nz/v1.1/transaction/oepayment/. For example, the full URL for the Sandbox environment oepayment endpoint is https://apitest.paymark.nz/v1.1/transaction/oepayment/.

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

EXCEPTION HANDLING When creating a resource, any non-response or 5xx HTTP errors should be treated as an exception. 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.


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.

AUTHENTICATION Online EFTPOS v1.1 uses the OAuth 2.0 client credentials flow (detailed in https://tools.ietf.org/html/rfc6749#section-4.4) for authentication. 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. Before calling any Online EFTPOS v1.1 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.


HTTP REQUEST Example Request POST /bearer HTTP/1.1 grant_type=client_credentials Authorization: Basic Base64Encoded(consumerKey:consumerSecret) Content-Type: application/x-www-form-urlencoded

HTTP RESPONSE If successful, returns HTTP 200 OK with the response body containing the oauth resource. Example Response HTTP/1.1 200 OK { "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" }


MESSAGE SIGNATURES 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 public signing key is shown below. -----BEGIN PUBLIC KEY-----

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAx3rO1Ixy3zdOyYGYY9+A

xYXJB8ex+bhv6CDAs4rcOp9FJgzGHQbXVZMZJh3DgH7EryrB+2bwe+ur9jsZIqxn

FJjOMbXcO57fcIZbTOUhA5D4PosZTAJWHEQ+EIdvmi8XZtnChKcoS9w0EoC2nPtx

6iWQSvNS+bChf1irnP3jC3NhpVWNKabQ8VmNxN7GM+dM5hteeOr8s/5pj0RGfK/H

mwRZFHkrnaGK+1bdrUQ2FkYv2rcEyLWzNthRITqS4Kich12E2TZYtcEeGMe8YQZi

hZyj/om5fJFBl0wuFv/rwcnf6oSmikt0cLpyJJuy1kcWn+IK8tCBro4O/ng2VGeD

Z0Ihj7V7kRzQAaaUCPL69XN7SIveWMdsOwG88SmmUHEnxUuMZvXHDBhfMtPjFG9z

o1CO4mi37aD3860AvoMewxKEtGDjX2aqAl9ofIMxn60AWrmLkbzk1ebtruDXjVvL

xQDwPWu0ot8mmCek3bwenJtCUG4u4N5kEWyyrupMGQnHsCP9xw/NgexM1rigC39Q

Fc42SE0dAk/mkg2BbFXNv5CUZ0nitt96xJQQT8KYSx7Odn8zndj1b0+l5t0zKvuT

/XNFseR6CCY0RJj5eIkJR6CSzYM20p8kfOA7PZBvff4QvtXtg89Uwkhpv+nw+WDj

/PU/O2eM22DT1550SrPOLVkCAwEAAQ==

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


OEPAYMENT An OE 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, the request will fail. API client must provide a valid OAuth token with their request.

POST 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 (c.f. Merchant Callback section).


HTTP REQUEST POST /v1.1/transaction/oepayment/

Request Body Provide a JSON formatted oepayment resource as below: Example Request POST /v1.1/transaction/oepayment/ HTTP/1.1

Accept: application/vnd.paymark_api+json

Content-Type: application/vnd.paymark_api+json

{

"bank": {

"payerId": "0215551234",

"bankId": "ASB",

"payerIdType": "MOBILE"

},

"merchant": {

"merchantIdCode": "301234567",

"merchantUrl": "www.widgets.co.nz",

"callbackUrl": "www.widgets.co.nz/callback?order=145"

},

"transaction": {

"amount": 1000,

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

}

}


HTTP RESPONSE If successful, returns HTTP 201 Created with the response body containing the oepayment resource. Example Response HTTP/1.1 201 Created

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

{

"id": "381a08c8-9189-4995-b07b-6c3821f70e35",

"status": "SUBMITTED",

"bank": {

"payerId": "0215551234",

"bankId": "ASB",


},

"merchant": {



},

"transaction": {

"amount": 1000,

"currency": "NZD",


"orderId": "145"

},

"creationTime": "2016-01-01T11:59:59Z",

"modificationTime": "2016-01-01T12:01:02Z",

"links": [

{

"href":

"https://apitest.uat.paymark.nz/v1.1/transaction/oepayment/381a08c8-9189-

4995-b07b-6c3821f70e35",

"rel": "self"

}

]

}


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

INDIVIDUAL PAYMENT To make this query, the API client must supply the UUID of the resource with the request. HTTP Request GET /v1.1/transaction/oepayment/<uuid>

Request Body None. Example Request GET /v1.1/transaction/oepayment/381a08c8-9189-4995-b07b-6c3821f70e35 HTTP/1.1



HTTP Response If successful, returns HTTP 200 OK with the response body containing the oepayment resource. Example Response HTTP/1.1 200 OK


{

"id": "381a08c8-9189-4995-b07b-6c3821f70e35",


"bank": {

"payerId": "0215551234",

"bankId": "ASB",


},

"merchant": {



},

"transaction": {

"amount": 1000,

"currency": "NZD",


"orderId": "145"

},

"creationTime": "2016-01-01T11:59:59Z",


"links": [

{

"href":

"https://apitest.uat.paymark.nz/v1.1/transaction/oepayment/381a08c8-9189-

4995-b07b-6c3821f70e35",

"rel": "self"

}

]

}


MULTIPLE PAYMENTS Multiple payments can be queried, and specific information on each payment can be retrieved. The results of the query are paginated (see also HATEOAS and Pagination section). 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:

orderId1 merchantIdCode payerId creationTime status

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

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

1 The orderId does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.


HTTP Request GET /v1.1/transaction/oepayment/?querycriteria

Request Body None. Example Request GET /v1.1/transaction/oepayment/?payerId=0215551234&offset=0fe3085c-1f8a-

4830-b587-f778d0f5340a&limit=1 HTTP/1.1



HTTP Response If successful, returns HTTP 200 OK with the response body containing the array of oepayment resources. Example Response HTTP/1.1 200 OK


{

"links": [

{ "href":

"https://api.paymark.nz/v1.1/transaction/oepayment/?payerId=0215551234&offset=0

fe3085c-1f8a-4830-b587-f778d0f5340a&limit=2",

"rel": "self",

"title": "List of OEPayment resources"

},

{ "href": "https://api.paymark.nz/v1.1/transaction/oepayment/381a08c8-9189-

4995-b07b-6c3821f70e35",

"rel": "381a08c8-9189-4995-b07b-6c3821f70e35"

},

{ "href": "https://api.paymark.nz/v1.1/transaction/oepayment/947a08c8-3856-

4995-b07b-3x9384f70e35",

"rel": "947a08c8-3856-4995-b07b-3x9384f70e35"

},

{ "href":


18800a4-376a-4ee1-8e56-4a64efcb27b4&limit=2",

"rel": "prev"

},

{ "href":


6510f43-eae6-40ab-86b7-9e4e98636137&limit=2",

"rel": "next"

}

],

"oepayments": [

{

"id": "381a08c8-9189-4995-b07b-6c3821f70e35",


"bank": {

"payerId": "0215551234",

"bankId": "ASB",



},

"merchant": {



},

"transaction": {

"amount": 1000,

"currency": "NZD",


"orderId": "145"

},

"creationTime": "2016-01-01T11:59:59Z",

"modificationTime": "2016-01-01T12:00:02Z"

},

{

"id": "947a08c8-3856-4995-b07b-3x9384f70e35",


"bank": {

"payerId": "0215551234",

"bankId": "ASB",


},

"merchant": {



},

"transaction": {

"amount": 5000,

"currency": "NZD",

"description": "Big Widget",

"orderId": "987"

},

"creationTime": "2016-01-16T12:01:59Z",


}

]

}


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 currency POST No description POST No orderId POST No userAgent POST Yes userIpAddress POST Yes

Notes on orderId:

This is used in 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.

Special characters are not permitted, namely: @ # ^ ' % & | > < " ; . \ / ! : ,


OEREFUND An OE 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. For refunds, a Merchant’s account must be in good standing, and business rules will apply – contact your Account Manager for more details. API client must provide a valid OAuth token with their request.

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. Partial refund for $30 exists in a 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.

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. C.f. Payment Required – 402.

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


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

HTTP REQUEST POST /v1.1/transaction/oerefund/

Request Body Provide a JSON formatted oerefund resource as below: Example Request POST /v1.1/transaction/oerefund/ HTTP/1.1


Content-Type: application/vnd.paymark_api+json

{

"merchant": {

"merchantIdCode": "301234567"

},

"transaction": {

"refundAmount": 1000,

"refundReason": "Defective goods",

"refundId": "145",

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

}

}


HTTP RESPONSE If successful, returns HTTP 201 Created with the response body containing the oerefund resource. Example Response HTTP/1.1 201 Created


{

"id": "3c6682fd-4532-499c-b9fc-890943e82a66",

"status": "REFUNDED",

"bank": {

"payerId": "0215551234",

},

"merchant": {


},

"transaction": {



"refundId": "145",


},

"creationTime": "2016-01-02T11:59:59Z",


"links": [

{

"href":

"https://apitest.uat.paymark.nz/v1.1/transaction/oerefund/3c6682fd-4532-

499c-b9fc-890943e82a66",

"rel": "self"

}

]

}


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

INDIVIDUAL REFUND To make this query, the API client must supply the UUID of the resource with the request. HTTP Request GET /v1.1/transaction/oerefund/<uuid>

Request Body None. Example Request GET /v1.1/transaction/oerefund/3c6682fd-4532-499c-b9fc-890943e82a66

HTTP/1.1



HTTP Response If successful, returns HTTP 200 OK with the response body containing the oerefund resource. Example Response HTTP/1.1 200 OK


{

"id": "3c6682fd-4532-499c-b9fc-890943e82a66",


"bank": {

"payerId": "0215551234",

},

"merchant": {


},

"transaction": {




},

"creationTime": "2016-01-02T11:59:59Z",


"links": [

{

"href":

"https://apitest.uat.paymark.nz/v1.1/transaction/oerefund/3c6682fd-4532-

499c-b9fc-890943e82a66",

"rel": "self"

}

]

}


MULTIPLE REFUNDS Multiple payments can be queried, and specific information on each payment can be retrieved. The results of the query are paginated (see also HATEOAS and Pagination section). 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:

refundId2 merchantIdCode payerId creationTime status

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

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

2 The refundId does not need to be unique, however, it is recommended this is unique to facilitate tracking of transactions.


HTTP Request GET /v1.1/transaction/oerefund/?querycriteria

Request Body None. Example Request GET /v1.1/transaction/oerefund/?payerId=0215551234 HTTP/1.1



HTTP Response If successful, returns HTTP 200 OK with the response body containing the array of oerefund resources. Example Response HTTP/1.1 200 OK


{

"links": [

{ "href":

"https://api.paymark.nz/v1.1/transaction/oerefund/?payerId=0215551234&offset=0b

d97e86-b597-4335-a120-15b1cf34a8a0&limit=2",

"rel": "self",

"title": "List of OERefund resources"

},

{ "href": "https://api.paymark.nz/v1.1/transaction/oerefund/3c6682fd-4532-

499c-b9fc-890943e82a66",

"rel": "3c6682fd-4532-499c-b9fc-890943e82a66"

},

{ "href": "https://api.paymark.nz/<version>/transaction/oerefund/9f3u08c8-

0386-8395-b07b-3x9384f70e9d",

"rel": "9f3u08c8-0386-8395-b07b-3x9384f70e9d"

},

{ "href":

"https://api.paymark.nz/v1.1/transaction/oerefund/?payerId=0215551234&offset=

e7424c00-15ab-4ead-a822-4199e6b38dab&limit=2",

"rel": "prev"

},

{ "href":

"https://api.paymark.nz/v1.1/transaction/oerefund/?payerId=0215551234&offset=

b89bb5ee-05ff-45a0-8bdd-df6c97d65559&limit=2",

"rel": "next"

}

],

"oerefunds": [

{

"id": "3c6682fd-4532-499c-b9fc-890943e82a66",


"bank": {

"payerId": "0215551234",

},

"merchant": {



},

"transaction": {



"refundId": "R145",


},

"creationTime": "2016-01-02T11:59:59Z",


}

{

"id": "9f3u08c8-0386-8395-b07b-3x9384f70e9d",


"bank": {

"payerId": "0215551234",

},

"merchant": {


},

"transaction": {



"refundId": "R987",

"originalPaymentId": "947a08c8-3856-4995-b07b-3x9384f70e35",

},

"creationTime": "2016-01-17T11:59:59Z",


}

]

}


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

Special characters are not permitted, namely: @ # ^ ' % & | > < " ; . \ / ! : ,


MERCHANT CALLBACK The callback is used to notify the API client about the transaction status of a payment. A callback is always provided, 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. API client will receive a POST request to the callback URL with the following form parameters: Field Description

merchantOrderId orderId sent with the original request status Refer to OEPayment section in Status Tables. signature Base64 encoded digital signature of the following String:

merchantOrderId=<mOId>&status=<status> Important: The Merchant callback URL is recommended to return a 200 OK status code in case of success. The status code is ignored and no further processing is done by Paymark if the Merchant 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 this response is not provided the API client needs to query the refund state until a terminal state is reached: refer to GET section in OERefund and OERefund section in Status Tables.

Important Note: If the response is not returned immediately the Merchant should not attempt the same refund again.


FIELD GLOSSARY id

Type String Format "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" Description Paymark-generated universally unique identifier for the

resource. payerId

Type String Format [+]{0,1}[0-9]{8,14} Description Payer’s identifier (mobile phone number).

bankId

Type String Format Fixed values, currently “ASB” only. Description The Consumer bank to which the payment request is sent.

payerIdType

Type String Format Fixed values, currently “MOBILE” only. Description Defines the type of payerId that has been used.

Note: Each bank allows different types. Refer to payerIdType and bankId Mapping section.


merchantId

Type String Format "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" Description Paymark-provided universally unique identifier for the resource.

merchantIdCode

Type String Format "30XXXXXXX" Description 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

Type String Format URL format Description Location of Merchant's website.

callbackUrl

Type String Format URL format including any query string parameters and values Description 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.

amount

Type Integer Format Numeric characters only Description Financial amount of transaction, in smallest units of currency

e.g. cents for NZD.


currency

Type String Format [A-Z]{3} Description ISO-4217 (alpha-3) currency code. Defaults to NZD.

description

Type String Format Up to 12 characters Description Merchant's description of purpose of payment.

orderId

Type String Format Up to 100 characters (recommend 12 characters max) Description Merchant’s order reference. 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

Type String Format Up to 8192 bytes Description Browser user agent detected by Merchant web server.

userIpAddress

Type String Format IPv4 address in dot notation, or IPv6 in colon notation Description Browser's IP address detected by Merchant web server.


status

Type String Format Fixed values Description See resource’s section in Status Tables.

creationTime

Type Timestamp Format YYYY-MM-DDTHH:mm:ssZ Description Date and time that Paymark resource was created.

modificationTime

Type Timestamp Format YYYY-MM-DDTHH:mm:ssZ Description Last date and time that Paymark resource was modified.

refundId

Type String Format Up to 100 characters (recommend 12 characters max) Description Merchant’s refund reference. 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

Type Integer Format Numeric Description Amount to refund to Consumer's bank account.


refundReason

Type String Format Up to 512 characters Description Cause of refund as indicated by Merchant.

originalPaymentId

Type String Format "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" Description UUID of the original payment that is being refunded; used to

validate refundAmount.

PAYERIDTYPE AND BANKID MAPPING Each Consumer bank can allow different types in payerIdType. The table below shows what is allowed by each Consumer bank (as specified in bankId). Bank (bankId) Allowed Types (payerIdType)

ASB MOBILE


STATUS TABLES

OEPAYMENT Valid values for the “status” field of an oepayment resource. These are set by Paymark, and cannot be modified by the API client. State Description Next States

NEW A new payment request from a Merchant, which has not been processed yet.

SUBMITTED, ERROR

SUBMITTED A payment request which has been sent to a Bank for processing, and for which the Bank has acknowledged the request.

AUTHORISED, DECLINED, EXPIRED

AUTHORISED A payment request, for which the Bank has notified Paymark that the Consumer (account holder) has authorised the payment.

REFUNDED

DECLINED A payment request, for which the Bank has notified Paymark that the payment has been declined, either by the Consumer (account holder) or the Bank itself. C.f. Sandbox Environment section for decline scenarios.

Terminal

REFUNDED A payment request which was successfully authorised, but which has been subsequently successfully refunded (partially or in full).

REFUNDED

ERROR A payment request could not be successfully sent to the Bank.

Terminal

EXPIRED A payment request, for which the Bank has notified Paymark that the expiry timeout has been passed.

Terminal


OEREFUND Valid values for the “status” field of an oerefund resource. These are set by Paymark, and cannot be modified by the API client. State Description Next States

UNSUBMITTED 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 e.g. due to insufficient funds, or other business logic.

Terminal

ERROR Bank responded to refund request with a system error.

Terminal


ERROR MESSAGES Example error message responses and formats.

VALIDATION ERRORS

GENERIC 400 ERROR {

"error": "validation"

}

This could be returned in any of the following cases:

The data passed in was not incorrect format (i.e. JSON) Attempting to parse a field as the wrong type

o String field trying to be converted to an integer A message may be parsed in (passing the above checks) but may then fail on certain things such as:

String too long Incorrect format (e.g. phone number containing letters)

If this is the case, the error response contains a bit more information to help the 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. Note: This is a future development; this scenario will currently generate a generic 400 error. {

"error" : "insufficient clear funds for refund"

}

FORBIDDEN – 403 {

"error" : "forbidden"

}

NOT FOUND – 404 No body provided as API clients have all the information to deal with this response.


METHOD NOT ALLOWED – 405 {

"error": "UnsupportedMediaType",

"reference": "<uuid>"

}

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 o "Phone number already registered"

Attempting to update an object that has changed since the API client last retrieved it.

o This is done via the dateModified field {

"error:": "conflict",

"messages": [

{

"message": "Conflicting field"

}

]

}

UNSUPPORTED MEDIA TYPE – 415 {

"error": "UnsupportedMediaType",


}


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 that they can quote it back to Paymark if they would like some more information. The reference is logged alongside the exception in the logs. {

"error": "Service Unavailable",


}


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: links to next and previous links in paginated resources. If there is another page of search results, a next link 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 creation time then ID. Specifying an 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 ENVIRONMENT The Sandbox environment can be used to simulate payment and refund operations. 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 access details.

PAYMENT REQUEST Transaction Amount

Response Description Response Type

Authorised Scenarios Any amount under $100 or over $120

Consumer has authorised the payment.

Consumer response

Declined Scenarios $117 Payment declined by the Consumer. Consumer response $101 Consumer does not have a Bank

mobile app registered for this mobile number.

System response

$102 Consumer not registered for PayHere (Online EFTPOS through ASB).

System response

$103 Consumer is not active at this Bank. System response $104 Consumer has no default bank

account. System response

$105 Consumer is over their account limit. System response Expired Scenarios $118 Consumer did not action the payment

request within four minutes (expiry timeout has been passed).

(Lack of) Consumer response

Error Scenarios $119 Error when Consumer tried to action

the payment request. Consumer response

$108 Bank system issue. System response $111 Duplicate payment request. System response $112 Paymark system issue (refer to

Paymark). System response

$113 Paymark system issue (Online EFTPOS disabled for this Bank).

System response

$115 Payment request formatted incorrectly. System response $116 Paymark system issue

(authentication). System response


REFUND REQUEST Transaction Amount

Response Description Response Type

Authorised Scenarios Any amount under $100 or over $120

Refund has been successfully processed.

Bank response

Declined Scenarios $101 Consumer does not have a Bank

mobile app registered for this mobile number.

System response

$102 Consumer not registered for PayHere (Online EFTPOS through ASB).

System response

$103 Consumer is not active at this Bank. System response $104 Consumer has no default bank

account. System response

$105 Consumer is over their account limit. System response Error Scenarios $108 Bank system issue. System response $111 Duplicate refund request. System response $112 Paymark system issue (refer to

Paymark). System response

$113 Paymark system issue (Online EFTPOS disabled for this bank).

System response

$115 Refund request formatted incorrectly. System response $116 Paymark system issue

(authentication). System response

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

Documents

Online EFTPOS v1.1 API Documentation - Amazon S3 · API client must provide a valid OAuth token with their request. POST Create a new request, ... AppleWebKit/537.36 (KHTML, like