Merchant Instore API Spec (1.0.3)

Download OpenAPI specification:Download

Change Log

1.0.3

  • Regenerate spec

1.0.2

  • Documented generic error codes

1.0.1

  • Documented error response schema

1.0.0

  • No change. Promoted version from beta to stable, ready for production.

0.6.1

  • Add Approve Purchase transaction example.

0.6.0

  • Add Transaction API, Pagination, Rate Limits sections.

0.5.0

  • Add validation for terminal_standalone_state.session_expire_ts

0.4.0

  • Set minimum value of 0 for standalone_config.fees[i].value and standalone_config.(merchant_receipt|customer_receipt).conditions[i].value

0.3.2

  • Updated descriptions of terminal_standalone_state properties
  • Updated regex pattern for alpha-num

0.3.1

  • Removes "NONE" enum value (fee.mode, (merchant_receipt|customer_receipt)conditions[i].mode)

0.3.0

  • Removes TerminalStandalone.state_template_vars in request and response.
  • Updates Request attributes limits and allowed characters for all end points.

0.2.2

  • Updates API base URLs.

0.2.1

  • Adds X-Request-ID in response header.

0.2.0

  • Responses are now wrapped in a data object

0.1.0

  • draft version

Versioning

All requests to this API will receive the current default version (current v1) if no Accept-Version request header is provided. We encourage you to explicitly set this version via the Accept-Version header.

  Accept-Version: v1

Request Headers

The below table summarises the request headers this API expects for all end points:

Header name Header value Required
Accept-Version v1 No
Authorization ApiKey [ApiKey] Yes

Example:

curl  -H "Authorization: ApiKey eefsdfdsdb1631c4746fe41e123ee10ebe69b9f5e==" \
      -H "Accept-Version: v1" \
      https://api[-sb].<bank-specific-domain.com>/instore/standalone-configs

Response Headers

Each API request is associated with a request ID available in the X-Request-ID response header. This value is created by the API and uniquely identifies your request. If you need to contact us to trouble shoot a scenario please include this request ID in your communication.

This value is safe and recommended to log

Pagination

All list API end points share a common structure, taking at least these two parameters: page_size, next_page_token

List query string parameters

  • page_size optional default is 10. It limits the number of items to be returned, between 1 and 100

  • page_token optional default to first page. It represents the pagination token to retrieve the next page of result.

    To retrieve the next page of results, client shall pass the value of response's meta.next_page_token in the subsequent list call (in the request message's page_token field)

List response payload

  • data array of items
  • meta where the response pagination data will be centralised
    • next_page_token represents the pagination token to retrieve the next page of results. If omitted, it means no further results for the request

Rate Limits

This API will allow up to 20 requests per seconds per IP.

Errors

The API uses conventional HTTP status codes to indicate the success or failure of the API call.

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate a client error that failed given the information provided.
  • Codes in the 5xx range indicate an error with our servers. Upon receiving 500 errors please quote the returned X-Request-ID value in the response header when asking for assistance.

All API endpoints include an error attribute in their response body when the request fails.

A typical error response has the below schema.

  • error.code and errors.fields are optional.
  • errors.fields is mostly found in 400 HTTP error to help targeting which field(s) is causing the error
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request",
    "fields": [
      {
        "field": "transaction_ts_ms_gteq",
        "description": "Missing field"
      },
      {
        "field": "transaction_ts_ms_lteq",
        "description": "Missing field"
      }
    ]
  }
}

Generic Error Codes

We have provided a list of generic error codes that can be used in a similar way to the http status.

We recommend that the status takes priority for all of these generic error codes but these can be used to further show that the error was caused by the application rather than some other issue like network.

Error Code HTTP Status Description Resolution
generic_bad_request 400 The provided request is invalid. Check all fields provided are valid.
generic_unauthorized 401 The request was not authorized. Check your authentication header to ensure it is correct.
generic_forbidden 403 You are forbidden from performing the action. Ensure the action you are performing is against a taget you have access to.
generic_not_found 404 The resource was not found. Ensure resource you are performing the action against exists.
generic_conflict 409 The resouce is in a conflicting state. Check the resource and try again.
generic_unprocessable_entity 422 There was a pre-condition that failed on the resource. Check the resource and try again.
generic_too_many_requests 429 Too many requests have been received in a short period of time. Wait a moment and try again.
generic_request_cancelled 499 The original request has been cancelled. Allow the request to complete.
generic_not_implemented 501 The requested functionality has not yet been implemented. Check the spec to ensure the functionality is ready for use.
generic_service_unavailable 503 The service is currently unavailble. Wait a moment and try again.
generic_gateway_timeout 504 The service has timed-out trying to process your request. Wait a moment and try again.

CustomError Codes

Some 4xx errors that could be handled programmatically include an error.code that briefly explains the error reported. Below is a list of possible error codes that can be returned, along with additional information about how to resolve them

Error Code HTTP Status Description Resolution
invalid_request 400 The provided request is invalid. Check the invalid fields in error.fields property in the error payload, and ensure that the format and value of all fields you passed in are valid.
request_body_should_be_omitted 400 A request body was provided This end point does not support body payload. Please remove it.
json_body_invalid 400 Request body contains badly-formed JSON Check the syntax error in the JSON request body and ensure that the request is in the correct JSON format.
accept_version_header_invalid 400 The provided Accept-Version request header value is invalid Ensure the value matches the supported versions.
api_key_missing 400 Missing API key in Authorization header (e.g. 'Authorization: ApiKey YOUR_KEY') Ensure you provide an API key in request header.
api_key_invalid 401 An invalid API key has been provided. Ensure you pass a valid API key.
transaction_not_found 404 The requested transaction cannot be found. Ensure that the specified transaction exists and belongs to your Organisation.
merchant_facility_not_found 404 The requested Merchant Facility cannot be found. Check your MID and ensure it exists and belongs to your Organisation.
standalone_config_not_found 404 The requested Standalone Config cannot be found. Check your Standalone Config ref and ensure it exists.
terminal_vaa_mode_not_allowed 422 Changing to this VAA mode not allowed. Contact support to make sure your terminal supports this mode.
invalid_terminal_type 422 Invalid terminal type, action can only be performed on a hardware terminal. Make sure the targeted terminal is a hardware terminal.

Guides

Configuring Terminal Standalone Config

  1. Create a Standalone Config
curl -X POST -H "Authorization: ApiKey XX" \
      https://api[-sb].<bank-specific-domain.com>/instore/standalone-configs/my-unique-id   \
      {
        [...]
      }
  1. Assign the newly created Standalone Config to a Merchant Facility that your Terminal belongs to:
curl -X PUT -H "Authorization: ApiKey XX" \
      https://api[-sb].<bank-specific-domain.com>/instore/merchant-facilities/{mid}/standalone-config/my-unique-id
  1. (optional) each time a new operator uses the Terminal, update its Terminal Standalone State
curl -X PUT -H "Authorization: ApiKey XX" \
      https://api[-sb].<bank-specific-domain.com>/instore/terminals/{tid}/standalone-state
      {
        [...]
      }
  1. Update Terminal vaa_mode to STANDALONE so that it going forward picks this Standalone Config. This migrates your terminnal from INTEGRATED to STANDALONE mode
curl -X PUT -H "Authorization: ApiKey XX" \
      https://api[-sb].<bank-specific-domain.com>/instore/terminals/{tid}/update-vaa-mode
      {
        "vaa_mode": "STANDALONE"
      }

NOTES:

  • Step 1 and 2 are usually done once for a merchant facility.
  • Step 3 is usually done each time a new operator uses the Terminal.
  • Step 4 is usually done once per terminal or each time we want to change the VAA mode.

Authentication

SecretApiKey

The instore merchant API secret key can be self-generated in the Merchant Dashboard. This key should only be used for backend to backend communication and should not exposed publically. Usage format: Authorization: ApiKey <YOUR_API_KEY>

Security Scheme Type HTTP
HTTP Authorization Scheme ApiKey

Standalone Configs

Operations about Standalone Config

Create or Update a Standalone Config with predefined client ref

Update a Standalone Config with predefined client reference.

Authorizations:
path Parameters
client_ref
required
string <= 50 characters ^[-.a-zA-Z0-9_]+\z

The client reference for this Standalone Config. It uniquely identifies this config.

Request Body schema: application/json
name
string

The user friendly name of the Standalone Config

login_mode
string
Default: "NONE"
Enum: "NONE" "REMOTE" "LOCAL"

Terminal login mode (local pin as opposed to REMOTE login). NONE means no login.

fees
Array of objects <= 25 items
merchant_receipt
object (TerminalReceipt)
customer_receipt
object (TerminalReceipt)

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

put /standalone-configs/{client_ref}

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/standalone-configs/{client_ref}

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/standalone-configs/{client_ref}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Qld Config",
  • "login_mode": "REMOTE",
  • "fees":
    [
    ],
  • "merchant_receipt":
    {
    },
  • "customer_receipt":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Merchant Facilities

Operations about Merchant Facilities

Sets Merchant Facility's Standalone Config

It sets (replaces if already exists) a Standalone Config to a merchant facilities

Authorizations:
path Parameters
mid
required
string

The Merchant ID

standalone_config_client_ref
required
string

The client reference for this Standalone Config. It uniquely identifies this config.

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

put /merchant-facilities/{mid}/standalone-config/{standalone_config_client_ref}

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/merchant-facilities/{mid}/standalone-config/{standalone_config_client_ref}

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/merchant-facilities/{mid}/standalone-config/{standalone_config_client_ref}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Terminals

Operations about Terminals

Create or Update a Standalone State for a Terminal

Update a Terminal Standalone State and replace all the values with the provided one. If any request properties are not provided they will be set with their default values.

Authorizations:
path Parameters
tid
required
string

The terminal ID (TID)

Request Body schema: application/json
operator_name
string <= 24 characters

The name of the operator Only used when Standalone Config's login_mode is set to REMOTE

operator_id
string <= 24 characters

The ID of the operator Only used when Standalone Config's login_mode is set to REMOTE

operator_pin
string <= 24 characters

Only used when Standalone Config's login_mode is set to LOCAL

session_expire_ts
integer

Epoch time in seconds since 1970 when the operator session should expire. Example 1580947134 means Wednesday February 5 2020 11:58:54 PM UTC Only used when Standalone Config's login_mode is set to REMOTE

If supplied, the value must not exceed +/- 50 years. This is to ensure that at least the input is not invalid

template_values
object

Templates values that will be used for generation of the Standalone Config's merchant_receipt and customer_receipt.

Property name contraints:

  • pattern: ^[-.a-zA-Z0-9_]+\z
  • max length: 32

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

422

The operation was rejected because the system is not in a state required for the operation's execution

put /terminals/{tid}/standalone-state

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/terminals/{tid}/standalone-state

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/terminals/{tid}/standalone-state

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "operator_name": "John Doe",
  • "operator_id": "0433765266",
  • "session_expire_ts": 1580947134,
  • "template_values":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Update VAA Mode

Update VAA Mode.

Authorizations:
path Parameters
tid
required
string

The terminal ID (TID)

Request Body schema: application/json
vaa_mode
required
string
Enum: "STANDALONE" "INTEGRATED"

The VAA mode we want the terminal to be on.

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

422

The operation was rejected because the system is not in a state required for the operation's execution

put /terminals/{tid}/update-vaa-mode

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/terminals/{tid}/update-vaa-mode

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/terminals/{tid}/update-vaa-mode

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "vaa_mode": "STANDALONE"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Transactions

Operations about Transactions

List Transactions

List transactions sorted by transaction_ts_ms DESC (most recent first)

Authorizations:
query Parameters
transaction_ts_ms_gteq
required
integer
Example: transaction_ts_ms_gteq=1585826324123

Return results where the transaction_ts_ms field is greater than or equal to this value.

In Unix timestamp in millis: since January 1, 1970 at 00:00:00.000 GMT

transaction_ts_ms_gteq must not be older than 12 months.

transaction_ts_ms_lteq
required
integer
Example: transaction_ts_ms_lteq=1585825814000

Return results where the transaction_ts_ms field is less than or equal to this value.

In Unix timestamp in millis: since January 1, 1970 at 00:00:00.000 GMT

Max range: transaction_ts_ms_lteq - transaction_ts_ms_gteq should be < 8 days.

page_size
integer [ 1 .. 100 ]
Default: 10
Example: page_size=5

Page size limit the number of results to be returned

page_token
string
Example: page_token=493c5435345b

Use the value from the meta.next_page_token from previous response to get results for the next page. Defaults to first page if not present.

mid
string
Example: mid=1234536

The Merchant ID (MID) provided by your acquiring bank.

Default to list all transactions belonging to your Organisation.

tid
string
Example: tid=1234536123

The terminal ID (TID) provided by your acquiring bank.

When provided along side a mid parameter, the tid must belong to the mid, otherwise an empty list will be returned.

card_transaction_details.rrn
string
Example: card_transaction_details.rrn=180815000003

The Retrieval Reference Number (RRN). Used to retrieve any transactions that match this RRN.

card_transaction_details.auth_code
string
Example: card_transaction_details.auth_code=705930

The Authorisation Code from the acquirer.

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

get /transactions

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/transactions

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/transactions

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "meta":
    {
    },
  • "data":
    [
    ]
}

Get a Transaction

Get a Transaction by Reference

Authorizations:
path Parameters
ref
required
string

The transaction ref

Responses

200

Success

400

Invalid Request

401

Unauthenticated error response

403

Forbidden error response

404

Not Found error response

get /transactions/{ref}

Live environment, please ask us for <bank-specific-domain.com> value

https://api.<bank-specific-domain.com>/instore/transactions/{ref}

Sandbox environment, please ask us for <bank-specific-domain.com> value

https://api-sb.<bank-specific-domain.com>/instore/transactions/{ref}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}