Download OpenAPI specification:Download
beta
to stable
, ready for production.terminal_standalone_state.session_expire_ts
0
for standalone_config.fees[i].value
and standalone_config.(merchant_receipt|customer_receipt).conditions[i].value
data
objectAll 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
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
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
All list API end points share a common structure, taking at least these two parameters: page_size
, next_page_token
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)
data
array of itemsmeta
where the response pagination data will be centralisednext_page_token
represents the pagination token to retrieve the next page of results. If omitted, it means no further results for the requestThe API uses conventional HTTP status codes to indicate the success or failure of the API call.
2xx
range indicate success.4xx
range indicate a client error that failed given the information provided.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"
}
]
}
}
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. |
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. |
curl -X POST -H "Authorization: ApiKey XX" \
https://api[-sb].<bank-specific-domain.com>/instore/standalone-configs/my-unique-id \
{
[...]
}
curl -X PUT -H "Authorization: ApiKey XX" \
https://api[-sb].<bank-specific-domain.com>/instore/merchant-facilities/{mid}/standalone-config/my-unique-id
curl -X PUT -H "Authorization: ApiKey XX" \
https://api[-sb].<bank-specific-domain.com>/instore/terminals/{tid}/standalone-state
{
[...]
}
vaa_mode
to STANDALONE
so that it going forward picks this Standalone Config.
This migrates your terminnal from INTEGRATED
to STANDALONE
modecurl -X PUT -H "Authorization: ApiKey XX" \
https://api[-sb].<bank-specific-domain.com>/instore/terminals/{tid}/update-vaa-mode
{
"vaa_mode": "STANDALONE"
}
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 |
Update a Standalone Config with predefined client reference.
client_ref required | string <= 50 characters ^[-.a-zA-Z0-9_]+\z The client reference for this Standalone Config. It uniquely identifies this config. |
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). |
fees | Array of objects <= 25 items |
merchant_receipt | object (TerminalReceipt) |
customer_receipt | object (TerminalReceipt) |
Success
Invalid Request
Unauthenticated error response
Forbidden error response
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "name": "Qld Config",
- "login_mode": "REMOTE",
- "fees": [
- {
- "template_var": "FARE_GST_AMOUNT",
- "display_text": "fare GST",
- "mode": "PERCENTAGE_ON_TOP_OF_ENTERED_TOTAL",
- "value": 909,
- "exclude_from_total": true
}, - {
- "template_var": "SERVICE_FEE_AMOUNT",
- "display_text": "service fee",
- "mode": "PERCENTAGE_ON_TOP_OF_ENTERED_TOTAL",
- "value": 500,
- "exclude_from_total": false
}, - {
- "template_var": "SERVICE_FEE_GST_AMOUNT",
- "display_text": "service fee GST",
- "mode": "PERCENTAGE_ON_OTHER_FEE",
- "value": 500,
- "target_fee": "SERVICE_FEE_AMOUNT",
- "exclude_from_total": true
}
], - "merchant_receipt": {
- "header": "Popeye Foods\nSYDNEY NSW 2000\n\n",
- "conditions": [
- {
- "type": "TOTAL_GREATER_THAN",
- "value": 8249,
- "content": "TAX INVOICE \n {{BUSINESS_NAME}} \n {{ABN}} \n INV #: {{REFERENCE_NUMBER}} \n\n"
}, - {
- "type": "TOTAL_LESS_THAN",
- "value": 8250,
- "content": "RECEIPT \n RECEIPT #: {{REFERENCE_NUMBER}} \n\n",
- "maxLength": 128
}
], - "footer": "Taxi: {{VEHICLE_PLATE}} \nDriver: {{DRIVER_AUTHORITY_NUMBER}}\n\nTotal Fare: {{ENTERED_AMOUNT}}\n Inc GST: {{FARE_GST_AMOUNT}}\nService Fee: {{SERVICE_FEE_AMOUNT}}\n Inc GST: {{SERVICE_FEE_GST_AMOUNT}}\n------------------\nTOTAL: {{GRAND_TOTAL}}\n------------------\n\nincludes Govt. Levy {{GOVT_LEVY}}\n\n----------------\n GET $20 CREDIT ON US\nDownload the popeye app and enter promo code\n\n {{PROMO_CODE}} \n\n popeyefoods.com.au/terms"
}, - "customer_receipt": {
- "header": "Popeye Foods\nSYDNEY NSW 2000\n\n",
- "conditions": [
- {
- "type": "TOTAL_GREATER_THAN",
- "value": 8249,
- "content": "TAX INVOICE \n {{BUSINESS_NAME}} \n {{ABN}} \n INV #: {{REFERENCE_NUMBER}} \n\n"
}, - {
- "type": "TOTAL_LESS_THAN",
- "value": 8250,
- "content": "RECEIPT \n RECEIPT #: {{REFERENCE_NUMBER}} \n\n",
- "maxLength": 128
}
], - "footer": "Taxi: {{VEHICLE_PLATE}} \nDriver: {{DRIVER_AUTHORITY_NUMBER}}\n\nTotal Fare: {{ENTERED_AMOUNT}}\n Inc GST: {{FARE_GST_AMOUNT}}\nService Fee: {{SERVICE_FEE_AMOUNT}}\n Inc GST: {{SERVICE_FEE_GST_AMOUNT}}\n------------------\nTOTAL: {{GRAND_TOTAL}}\n------------------\n\nincludes Govt. Levy {{GOVT_LEVY}}\n\n----------------\n GET $20 CREDIT ON US\nDownload the popeye app and enter promo code\n\n {{PROMO_CODE}} \n\n popeyefoods.com.au/terms"
}
}
{- "data": {
- "client_ref": "7f68e137-b011-435e-9b45-5e20fd743b34",
- "name": "Qld Config",
- "login_mode": "REMOTE",
- "fees": [
- {
- "template_var": "FARE_GST_AMOUNT",
- "display_text": "fare GST",
- "mode": "PERCENTAGE_ON_TOP_OF_ENTERED_TOTAL",
- "value": 909,
- "exclude_from_total": true
}, - {
- "template_var": "SERVICE_FEE_AMOUNT",
- "display_text": "service fee",
- "mode": "PERCENTAGE_ON_TOP_OF_ENTERED_TOTAL",
- "value": 500,
- "exclude_from_total": false
}, - {
- "template_var": "SERVICE_FEE_GST_AMOUNT",
- "display_text": "service fee GST",
- "mode": "PERCENTAGE_ON_OTHER_FEE",
- "value": 500,
- "target_fee": "SERVICE_FEE_AMOUNT",
- "exclude_from_total": true
}
], - "merchant_receipt": {
- "header": "Popeye Foods\nSYDNEY NSW 2000\n\n",
- "conditions": [
- {
- "type": "TOTAL_GREATER_THAN",
- "value": 8249,
- "content": "TAX INVOICE \n {{BUSINESS_NAME}} \n {{ABN}} \n INV #: {{REFERENCE_NUMBER}} \n\n"
}, - {
- "type": "TOTAL_LESS_THAN",
- "value": 8250,
- "content": "RECEIPT \n RECEIPT #: {{REFERENCE_NUMBER}} \n\n",
- "maxLength": 128
}
], - "footer": "Taxi: {{VEHICLE_PLATE}} \nDriver: {{DRIVER_AUTHORITY_NUMBER}}\n\nTotal Fare: {{ENTERED_AMOUNT}}\n Inc GST: {{FARE_GST_AMOUNT}}\nService Fee: {{SERVICE_FEE_AMOUNT}}\n Inc GST: {{SERVICE_FEE_GST_AMOUNT}}\n------------------\nTOTAL: {{GRAND_TOTAL}}\n------------------\n\nincludes Govt. Levy {{GOVT_LEVY}}\n\n----------------\n GET $20 CREDIT ON US\nDownload the popeye app and enter promo code\n\n {{PROMO_CODE}} \n\n popeyefoods.com.au/terms"
}, - "customer_receipt": {
- "header": "Popeye Foods\nSYDNEY NSW 2000\n\n",
- "conditions": [
- {
- "type": "TOTAL_GREATER_THAN",
- "value": 8249,
- "content": "TAX INVOICE \n {{BUSINESS_NAME}} \n {{ABN}} \n INV #: {{REFERENCE_NUMBER}} \n\n"
}, - {
- "type": "TOTAL_LESS_THAN",
- "value": 8250,
- "content": "RECEIPT \n RECEIPT #: {{REFERENCE_NUMBER}} \n\n",
- "maxLength": 128
}
], - "footer": "Taxi: {{VEHICLE_PLATE}} \nDriver: {{DRIVER_AUTHORITY_NUMBER}}\n\nTotal Fare: {{ENTERED_AMOUNT}}\n Inc GST: {{FARE_GST_AMOUNT}}\nService Fee: {{SERVICE_FEE_AMOUNT}}\n Inc GST: {{SERVICE_FEE_GST_AMOUNT}}\n------------------\nTOTAL: {{GRAND_TOTAL}}\n------------------\n\nincludes Govt. Levy {{GOVT_LEVY}}\n\n----------------\n GET $20 CREDIT ON US\nDownload the popeye app and enter promo code\n\n {{PROMO_CODE}} \n\n popeyefoods.com.au/terms"
}
}
}
It sets (replaces if already exists) a Standalone Config to a merchant facilities
mid required | string The Merchant ID |
standalone_config_client_ref required | string The client reference for this Standalone Config. It uniquely identifies this config. |
Success
Invalid Request
Unauthenticated error response
Forbidden error response
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "data": {
- "mid": "1234536",
- "standalone_config_client_ref": "7f68e137-b011-435e-9b45-5e20fd743b34"
}
}
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.
tid required | string The terminal ID (TID) |
operator_name | string <= 24 characters The name of the operator Only used when Standalone Config's login_mode is set to |
operator_id | string <= 24 characters The ID of the operator Only used when Standalone Config's login_mode is set to |
operator_pin | string <= 24 characters Only used when Standalone Config's login_mode is set to |
session_expire_ts | integer Epoch time in seconds since 1970 when the operator session should expire. Example 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 Property name contraints:
|
Success
Invalid Request
Unauthenticated error response
Forbidden error response
The operation was rejected because the system is not in a state required for the operation's execution
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "operator_name": "John Doe",
- "operator_id": "0433765266",
- "session_expire_ts": 1580947134,
- "template_values": {
- "BUSINESS_NAME": "MD Hammer",
- "ABN": "23 123 234 345",
- "REFERENCE_NUMBER": "RD8378",
- "VEHICLE_PLATE": "T3421",
- "DRIVER_AUTHORITY_NUMBER": "R8727J2",
- "GOVT_LEVY_AMOUNT": "$1.10",
- "PROMO_CODE": "ABC999"
}
}
{- "data": {
- "operator_name": "John Doe",
- "operator_id": "0433765266",
- "session_expire_ts": 1580947134,
- "template_values": {
- "BUSINESS_NAME": "MD Hammer",
- "ABN": "23 123 234 345",
- "REFERENCE_NUMBER": "RD8378",
- "VEHICLE_PLATE": "T3421",
- "DRIVER_AUTHORITY_NUMBER": "R8727J2",
- "GOVT_LEVY_AMOUNT": "$1.10",
- "PROMO_CODE": "ABC999"
}
}
}
Update VAA Mode.
tid required | string The terminal ID (TID) |
vaa_mode required | string Enum: "STANDALONE" "INTEGRATED" The VAA mode we want the terminal to be on. |
Success
Invalid Request
Unauthenticated error response
Forbidden error response
The operation was rejected because the system is not in a state required for the operation's execution
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "vaa_mode": "STANDALONE"
}
{- "data": {
- "tid": "1234536123",
- "vaa_mode": "STANDALONE"
}
}
List transactions sorted by transaction_ts_ms
DESC (most recent first)
transaction_ts_ms_gteq required | integer Example: transaction_ts_ms_gteq=1585826324123 Return results where the In Unix timestamp in millis: since January 1, 1970 at 00:00:00.000 GMT
|
transaction_ts_ms_lteq required | integer Example: transaction_ts_ms_lteq=1585825814000 Return results where the In Unix timestamp in millis: since January 1, 1970 at 00:00:00.000 GMT Max range: |
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 |
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 |
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. |
Success
Invalid Request
Unauthenticated error response
Forbidden error response
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "meta": {
- "next_page_token": "493c5435345b"
}, - "data": [
- {
- "ref": "4cb6cfd7-01dd-493c-9629-21375b599ad5",
- "approval_status": "APPROVED",
- "transaction_type": "PURCHASE",
- "amount_details": {
- "total": 1050,
- "purchase": 1050
}, - "currency": "AUD",
- "gateway_response_code": "001",
- "gateway_response_message": "APPROVE WITH SIG",
- "mid": "1234536",
- "tid": "1234536123",
- "operator_id": "op_1234567",
- "transaction_ts_ms": 1585904846123,
- "settlement_date": "2020-04-03",
- "pos_ref_id": "35808083",
- "payment_method": "CARD",
- "card_transaction_details": {
- "rrn": "180815000005",
- "account_type": "CREDIT",
- "scheme_app_name": "Visa",
- "auth_code": "705932",
- "card_details": {
- "last_digits": "1234",
- "expiry_month": 12,
- "expiry_year": 2020,
- "scheme": "VISA"
}
}
}, - {
- "ref": "4cb6cfd7-01dd-493c-9629-21375b599ad1",
- "approval_status": "DECLINED",
- "transaction_type": "PURCHASE",
- "amount_details": {
- "total": 1050,
- "purchase": 1050
}, - "currency": "AUD",
- "gateway_response_code": "001",
- "gateway_response_message": "APPROVE WITH SIG",
- "mid": "1234536",
- "tid": "1234536123",
- "operator_id": "op_1234567",
- "transaction_ts_ms": 1585904846123,
- "settlement_date": "2020-04-03",
- "pos_ref_id": "35808083",
- "payment_method": "CARD",
- "card_transaction_details": {
- "rrn": "180815000003",
- "account_type": "CREDIT",
- "scheme_app_name": "Visa",
- "auth_code": "705931",
- "card_details": {
- "last_digits": "1234",
- "expiry_month": 12,
- "expiry_year": 2020,
- "scheme": "VISA"
}
}
}
]
}
Get a Transaction by Reference
ref required | string The transaction ref |
Success
Invalid Request
Unauthenticated error response
Forbidden error response
Not Found error response
Live environment, please ask us for <bank-specific-domain.com>
value
Sandbox environment, please ask us for <bank-specific-domain.com>
value
{- "data": {
- "ref": "4cb6cfd7-01dd-493c-9629-21375b599ad8",
- "approval_status": "APPROVED",
- "transaction_type": "PURCHASE",
- "amount_details": {
- "total": 1050,
- "purchase": 1050
}, - "currency": "AUD",
- "gateway_response_code": "001",
- "gateway_response_message": "APPROVE WITH SIG",
- "mid": "1234536",
- "tid": "1234536123",
- "operator_id": "op_1234567",
- "transaction_ts_ms": 1585904846123,
- "settlement_date": "2020-04-03",
- "pos_ref_id": "35808083",
- "payment_method": "CARD",
- "card_transaction_details": {
- "rrn": "180815000003",
- "account_type": "CREDIT",
- "scheme_app_name": "Visa",
- "auth_code": "705930",
- "card_details": {
- "last_digits": "1234",
- "expiry_month": 12,
- "expiry_year": 2020,
- "scheme": "VISA"
}
}
}
}