The full changelog can be found here:

View changelog

This is the specification for a restful API for interfacing with the CAS payment gateway and customer information vault (CIV), enabling:

• purchases
• preauthorisations & completions
• refunds by audit
• standalone refunds
• voids by audit
• lookups of individual transactions
• credit card tokenisation

This specification conforms to the OpenAPI standard. There exist a number of tools to generate code stubs from an an OpenAPI specification, such as OpenAPI Generator and Swagger Codegen.

This API loosely conforms to the HAL standard. The only deviation from HAL is that the link relation types used in the _links response fields have been simplified without the use of CURIES.

The API is only intended for use by a backend server. It should not be used by the frontend of a website. Please contact CAS if you have any questions or for frontend payment and tokenisation options.

In every request made to the API (other than lookups), a correlation ID must be supplied by the client. This ID should be uniquely generated for each request. Every response for these operations (again excepting lookups) will contain the correlation ID of the corresponding request. This allows for asynchronous requests to be matched with their responses on the client side.

Transactions

Correlation IDs perform an additional role of ensuring idempotency in the case of transaction operations.

For transaction operations, correlation IDs must at least be uniquely generated for each merchant ID, although it is recommended to use a globally unique format such as UUID. If a transaction request times out or recieves a 5XX response, the correlation ID can be used to identify and lookup the status of any transaction that may have been created by the request. If that lookup returns a 404 Not Found response, the original transaction was not processed and it is safe to be retried (remember to use a different X-Correlation-Id).

Note that while the correlation ID can temporarily be used to identify a transaction, it is only cached in the gateway for a limited time (usually 24 hours). In all normal cases, the audit should be used to identify a transaction.

Tokenisation

As tokenisation operations are much lower risk than transaction operations, correlation IDs cannot be used in the same way. If the server times out or a 5XX response is recieved, simply perform a lookup on the relevant endpoint to see whether the previous request succeeded or not.

For example, if a POST request to /customers returns a 5XX HTTP status code or times out, make a GET request to /customers, optionally searching by the details of the new customer, to see whether or not the new customer was created.

The API only accepts a restricted set of ASCII characters in all string fields, as shown in the pattern validation of this specification. Accepted characters include all lower and upper case letters, all numeric digits, the space character, and the following punctuation: !#$%&()*+,-./:;<=>?@[]^_`{|}~.

The X-Correlation-Id field has a more restricted character set, excluding most punctuation and the space character.

KVP key names have a more restricted character set again, allowing only letters, digits and the underscore ( _ ) and period ( . ) characters.

The API will be updated over time to fix issues and introduce new functionality. To reflect this, each version is given a version number comprised of three parts: major, minor, and patch version.

• A major update is one in which existing functionality of the API is changed or removed in a breaking way as defined below.
• A minor update is one in which new functionality is introduced or existing functionality is augmented in non-breaking ways.
• A patch update is one in which only minor or error fixing changes are made. For example, the version number 1.4.2 denotes major version 1, minor version 4, and patch 2.

The major version number of the API is reflected in the URI. For example, the major version 1 of the API will use a URI similar to http://api.cardaccess.com.au/live/etx/txn/v1.

Updates to the API are separated into non-breaking and breaking changes depending on how they affect the functionality of the API; see below for their definitions. Non-breaking changes involve changing only the minor or patch version numbers; these changes may be applied to the API at any time and do not require introducing a new URI. Breaking changes will always be associated with changing the major version number, and thus using a different URI to the previous version. When a breaking change is introduced, the previous major version of the API will continue to be supported for a reasonable period of time. Clients will be notified of the date after which the old version will no longer be available and that a new version has been released.

Non breaking changes may be implemented on existing versions of this API. Clients should ensure that their applications can handle the following types of non-breaking change without prior notice:

Endpoints

• Addition of a new endpoint.
• Addition of a new HTTP method to an existing endpoint.
• Addition of a new optional query parameter to an existing HTTP method.
• Update of an existing query parameter from required to optional.

Request body

• Addition of a new optional field.
• Addition of a new supported value in an existing field.
• Update of an existing field from required to optional.

Response body

• Addition of a new field.
• Addition of a new value to an existing field where no definitive list of values has previously been specified.
• Addition of a new value to an existing field where a definitive list of values has been specified and one of the specified values is unknown or Unknown. In this case, the client application should treat any unrecognised value as being equivalent to unknown or Unknown.
• A value of -99 in status.gateway_status_code is considered equivalent to unknown, and so addition of a new supported value to this field is considered non-breaking. An unrecognised value for this field should be treated as equivalent to -99.
• Update to the value of a field ending in _message. Message text is intended for human interpretation; system logic should depend on the similar field ending in _code.
• Update to the order of fields.
• Update to the overall response length.

Request header

• Addition of a new optional request header.

Response header

• Addition of a new response header.

Security

• Addition of a new alternate security scheme.

Breaking changes will only be implemented in new major versions of this API. The following types of changes are considered breaking and do not need to be handled by client applications:

Endpoints

• Deletion of an existing endpoint.
• Deletion of an existing HTTP method from an existing endpoint.
• Addition of a new required query string parameter to an existing HTTP method.

Request body

• Addition of a new required field.
• Deletion of a field.
• Deletion of a supported value in an existing field.
• Update to the minimum or maximum length of a field or field name where a minimum or maximum length has previously been specified.
• Update to the type of an existing field.
• Update to the format or pattern of an existing field where a format or pattern has previously been specified.

Response body

• Deletion of a field.
• Addition of a new supported value for an existing field where a definitive list of values has previously been specified and none of the specified values are unknown or Unknown.
• A value of -99 in status.gateway_status_code is considered equivalent to unknown, and so addition of a new supported value to this field is considered non-breaking.
• Update to the minimum or maximum length of a field or field name where a minimum or maximum length has previously been specified.
• Update to the type of an existing field.
• Update to the format or pattern of an existing field where a format or pattern has previously been specified.

Request header

• Addition of a new required request header.

Response header

• Deletion of a response header.

Response status code

• Addition of a new HTTP status code response.
• Deletion of an existing HTTP status code response.

Security

• Addition of a new required security scheme.
• Update to an existing security scheme.
• Deletion of an existing security scheme.

Other

• Addition of any new request validation which changes the logic of the API. For example, a new validation which changes whether a request is accepted or rejected is considered a breaking change.

The behaviour of the API can be modified in fixed ways using plugins. Please contact CAS if you want to enable or configure any of these plugins.

Transaction Surcharges

Set a percentage surcharge to be added onto any payment transactions (purchases, preauthorisations and completions). The surcharge can be configured as a default percentage or specified for each payment method and card type.

In addition to modifying the total amount of the transaction, the following KVPs are added to describe the surcharge details:

Identification

Transactions are stored in the gateway and identified by their audit (also referred to as audit number). Each successful transaction request will create a new audit of the pertinent type: purchase, preauthorisation, completion, standalone refund, refund by audit, and void. Completions, refunds by audit and voids act on and refer back to the original transaciton, but are still considered individual transactions themselves. Merchants should record the audit for each transaction as a permanent reference for later refunds etc. CAS staff require the audit to identify a transaction when providing support.

HTTP Response Codes

A 2XX HTTP response code does not denote an approved transaction. It merely denotes that a response was received from the gateway.

In most cases, the status.transaction_status_code field can be used to determine the outcome of the transaction request. If its value is approved, the transaction has been approved. If its value is declined, the transaction has been declined. A value of pending denotes that the transaction is a direct debit transaction and is waiting for confirmation from the acquirer; This will usually take multiple working days. If its value is error, the fields status.gateway_status_code and status.acquirer.response_code can be used to diagnose the issue.

A 4XX HTTP response code denotes an improper request. The transaction is never approved.

In the event of a 5XX HTTP response code for a transaction request, it is strongly recommended that a lookup be called on either the audit, if given, or the idempotency key. An error may have occurred at any point in the chain between the client and the acquirer, so the transaction may have been approved or declined. If the lookup does not also return an error, it will show the status of the transaction. If the lookup returns a 404 HTTP response code, then the transaction was not processed and it can safely be reattempted.

Overview

Tokenisation is only available to merchants with the CIV product. Please contact CAS for more information or to request use of this product.

A token, also known as a registered account, is a stored payment method which can be used in later transactions. Sensitive payment information is stored in the customer information vault (CIV), and identified by the token ID. The Virtual PAN (VPAN) can then be used in place of the payment information when performing transactions on CAS systems.

Each token is owned by a customer. Customers usually correspond with the real customers of a merchant, but may be used as an arbitrary collection of tokens. A customer may have zero, one or many tokens.

Currently tokens can store either credit card or bank account details, however the tokenisation system has the capability to store other customer information. Please contact CAS if you have a use for storing extended information.