EML Data Services API documentation version 1.0

https://ws.emerchants.com.au/3.0/

Document Status

This document is currently Active

Introduction

This is a REST API provided by EML, and is invoked by our clients. It is used for performing a variety of management operations in the EML ecosystem.

Reading This Documentation

At the bottom of this page, you will find a list containing all of the resources provided by this API.

Clicking on a resource, /accounts for example, will reveal more information about its supported HTTP methods. Clicking on a method, GET for example, will bring up more detailed information, usage instructions, and examples.

Security

This API leverages OAuth 2.0 for authentication and authorization. OAuth 2 Simplified may be good to read if you want to learn more about it, though that's not necessary to use this API.

There are OAuth 2.0 client libraries available for many popular languages, which may simplify the integration process. If no library is available for your language, or you prefer to have more control, it is quite easy to implement the workflow yourself using simple HTTP and JSON.

The following paragraphs document the OAuth 2.0 workflow in detail.

Obtaining an access token

You will need to provide a valid access token when accessing any of this API's resources. Access tokens are obtained via a POST request to the /token resource.

This request must be made up of the following components:

  • Authorization header containing a valid client ID and secret. The value is constructed by combining the client ID and secret with a colon (id:secret), encoding the result using the RFC2045-MIME variant of Base64, and prepending Basic .
  • Content-Type header set to application/x-www-form-urlencoded
  • Body containing grant_type=client_credentials

See the example below:

    POST /3.0/token HTTP/1.1
    Host: ws.emerchants.com.au
    Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials

Given valid client credentials, the API will return a 200 OK response containing the following:

    {
        "access_token": "AcMCRbJRSmyLFbIRQxMvFB5xZ6cBjghjN3/YEoxGKWkKNZkqnfE=",
        "token_type": "bearer",
        "expires_in": 43199
    }

You should keep the value from access_token to include in subsequent requests, and be prepared to get a new access token before this one expires in expires_in seconds.

Using the access token

The access token obtained in the previous step can be used to access resources by sending it in the Authorization header of each request using the format: Bearer access_token. Here is an example of retrieving an account:

    GET /3.0/accounts HTTP/1.1
    Host: ws.emerchants.com.au
    Authorization: Bearer AcMCRbJRSmyLFbIRQxMvFB5xZ6cBjghjN3/YEoxGKWkKNZkqnfE=

Token expiration

You should continue to re-use the same access token until shortly before it expires. At this time, you should repeat the above steps to get a new access token.

The strategy you use to keep your access token valid is up to you, but one example strategy is as follows:

  • If, when attempting to use your current access token, there is less than 10 minutes remaining before it expires, trigger an asynchronous process to get a new access token.
  • If you receive a 401 UNAUTHORIZED response, trigger a synchronous process to get a new access token, and try again.

Access tokens will remain valid until they expire. It is safe to use multiple tokens concurrently while you complete the process of getting a new access token, and propagating it through your system.

IP Whitelisting

In addition to the OAuth 2.0 authentication and authorization, emerchants maintains a whitelist of I.P. addresses which are permitted to access the API. Before you can access either the test or the production endpoints, you will need to contact emerchants and provide us with the public I.P. addresses from which you wish to access the API. You may provide one or more IP addresses (or subnets) to be whitelisted in each environment. Be aware that we will not whitelist subnets larger than /29 (IPv4).

Please note that our policy dictates that a single IP address cannot be simultaneously whitelisted in both the test and production environments.

Be advised that there is some lead time involved with adding or modifying the whitelist.

Important Usage Note

All JSON sent to and from the API must be sent with the Content-Type HTTP header set to application/vnd.eml+json. This is to prevent any confusion caused by intermediate proxies and gateways which may send application/json under some conditions.

Test Environment

There is a test environment available at https://beta.emerchants.com.au/3.0/ which can be used for testing.

Code Examples

Below are some simple code snippets aimed at guiding you towards your implementation. These examples are written in C# .NET using a library called Flurl. This library wraps the standard HTTP classes in a fluent API, which should aid in understanding the code, even if C# isn't your language of choice.

Getting a token

private async Task<string> GetToken(string clientId, string clientSecret)
{
    try
    {
        dynamic json = await new Url("https://ws.emerchants.com.au/3.0/token")
            .WithHeader("Accept", "application/vnd.eml+json")
            .WithBasicAuth(clientId, clientSecret)
            .PostUrlEncodedAsync(new
            {
                grant_type = "client_credentials"
            })
            .ReceiveJson();

        // 200 OK

        string token = json.access_token;
        return token;
    }
    catch (FlurlHttpException ex)
    {
        switch (ex.Call.HttpStatus)
        {
            case HttpStatusCode.BadRequest: // usage doesn't match documentation
                throw;
            case HttpStatusCode.Unauthorized: // invalid client-id and/or client-secret
                throw;
            case HttpStatusCode.InternalServerError: // something happened on emerchants' end
                throw;
            default: // undocumented status code
                throw;
        }
    }
}

/token

post

post

Request an access token using the specified client credentials.

Request an access token using the specified client credentials.

Headers

  • Authorization: required(string)

    Constructed by combining the client ID and secret with a colon (id:secret), encoding the result using the RFC2045-MIME variant of Base64, and prepending Basic .

    Example:

    Basic W91cl9jbGllbnRfaWQ6eW91cl9jbGllbnRfc2VjcmV0

HTTP status code 200

You were authenticated and a token was generated successfully.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • access_token: required(string)
  • token_type: required(string)
  • expires_in: required(number)

Example:

{
    "access_token": "AcMCRbJRSmyLFbIRQxMvFB5xZ6cBjghjN3/YEoxGKWkKNZkqnfE=",
    "token_type": "bearer",
    "expires_in": 43200
}

HTTP status code 400

The request cannot be processed due to a problem with it. Check the error code and consult this documentation.

Possible error codes:

  • invalid_request
  • unsupported_grant_type
  • invalid_client (credentials are missing or incomplete)

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 401

The client credentials that were provided are incorrect. Please check them and try again.

Possible error codes:

  • invalid_client (credentials are incorrect)

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

/programs

get

get

Get the restriction ruleset for the program

Get the restriction ruleset for the program

Secured by

URI Parameters

  • id: required(number)

    The Program Id (Company Id) of the program.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • type: required(one of open, close)

    A type of restriction Open (Allows by default) or Close (Deny by default)

  • terminal_rules: required(array of object)

    A list of terminal rules which are applied.

    Items: TerminalRule

    • rule_type: required(must_allow must_block)
    • acquirer: required(string)
    • acceptor: required(string)
    • terminal: required(string)
  • category_rules: required(array of object)

    A list of category rules which are applied.

    Items: CategoryRule

    • rule_type: required(must_allow must_block)
    • category_code: required(string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

/accounts

get post

get

Perform an account search

post

create a new account

create a new account

Secured by

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • initial_load_amount: required(number)

    the amount to be loaded into the account. This value should be zero or more

  • name_on_card: (string - minLength: 2 - maxLength: 19)

    the card holder name to be printed on the physical card; valid characters include 0-9, A-Z, -, /, and .

  • initiating_user_id: (string)

    the user who initiated this request

  • portal_identifier: (object)

    The portal identifier associated with this account.

    • client_id: required(string)

      the client id assigned to the account

    • program_id: required(string)

      the program id assigned to the account

    • cardholder_id: required(string)

      the cardholder id assigned to the account

  • company_id: required(integer)

    the company id in which the account will be created

  • is_plastic_enabled: (boolean)

    the plastic enabled flag; the default value is true

  • plastic_expiry: (datetime)

    The plastic Expiry of the card. This field is only effective for card manufacturing batch with AllowCustomPlasticExpiry enabled. The date is in ISO 8601 UTC format. For example: 2018-02-24T09:02:10Z

  • client_account_key: (string - maxLength: 255)

    the client account key for salary packaging programs; valid characters are within the range of ASCII code 0x20 and 0x7E inclusive

  • registration: required(object)

    the client details including name, address and passport

    • driver_licence_number: (string - maxLength: 30)
    • alternate_address: (object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: (string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • first_name: required(string - maxLength: 50)
    • phone_number: (string - maxLength: 50)
    • sex: required(string)

      client gender; must be either 'M' or 'F'

    • mobile_number: (string - maxLength: 50)
    • middle_name: (string - maxLength: 50)
    • primary_address: required(object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • address_line3: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: required(string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • title: (string - maxLength: 50)
    • passport: (object)
      • passport_number: required(string - maxLength: 10)
      • passport_expiry: required(datetime)

        passport expiration date; must be later than current date

      • passport_issuing_country: required(string)

        ISO 3166 Alpha-3 country code

    • date_of_birth: required(datetime)
    • last_name: required(string)
    • email_address: required(string)

      client email address; must be a valid email addresss.

  • display_name: (string - maxLength: 100)

    the display name for FBT card program

Example:

{
  "company_id": 123456,
  "initial_load_amount": 10,
  "registration": {
    "first_name": "test",
    "last_name": "user",
    "email_address": "[email protected]",
    "primary_address": {
      "address_line1": "test address",
      "country": "AU",
      "state": "QLD"
    },
    "passport": {
      "passport_issuing_country": "AUS",
      "passport_expiry": "2020-10-31T01:00:00Z",
      "passport_number": "abc"
    },
    "sex": "M",
    "date_of_birth": "2000-10-01T01:00:01Z"
  },
  "initiating_user_id": "testuser"
}

HTTP status code 201

The operation was successful, and the account was created successfully

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • balance: required(number)

    The balance of the account.

  • card_number: required(string)

    The masked credit card number

  • company_id: required(integer)

    The company id

  • external_account_id: required(string)

    The external reference id

  • plastic_expiry: required(datetime)

    The plastic expiration date

  • product_type: required(one of reloadable, gift, loyalty)
  • status: required(one of active, pre_active, inactive, deactivated, lost_or_stolen, expired, suspected_fraud, closed, inactive_pin_tries_exceeded, eml_inactive, replaced)

    The status of the account.

  • is_plastic_enabled: required(boolean)

    The plastic_enabled flag. Either true or false.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

get put

get

Get the status of the account

put

update account details

Get the status of the account

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Query Parameters

  • with_personal: (string)

    Allows the caller to control whether the personal property is present on the response. To include the property, supply any non-whitespace value for the parameter, e.g., ?with_personal=1. To omit the property, simply omit this query parameter.

  • with_directentry: (string)

    Allows the caller to control whether the direct_entry_bsb and direct_entry_account_number properties are present on the response. To include the property, supply any non-whitespace value for the parameter, e.g., ?with_directentry=1. To omit the property, simply omit this query parameter.

  • with_freetext: (string)

    Allows the caller to control whether the free_text property is present on the response. To include the property, supply any non-whitespace value for the parameter, e.g., ?with_freetext=1. To omit the property, simply omit this query parameter.

  • with_bpay: (string)

    Allows the caller to control whether the bpay_biller_code and bpay_reference_number properties are present on the response. To include the property, supply any non-whitespace value for the parameter, e.g., ?with_bpay=1. To omit the property, simply omit this query parameter.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • direct_entry_account_number: (string)
  • account_type: required(one of proxy, ledger)

    The type of account. Either a proxy card or a salary-packaging ledger (benefit).

  • personal: (object)

    The registered personal information for the account holder.

    • driver_licence_number: (string - maxLength: 30)
    • alternate_address: (object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: (string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • first_name: required(string - maxLength: 50)
    • phone_number: (string - maxLength: 50)
    • sex: required(string)

      client gender; must be either 'M' or 'F'

    • mobile_number: (string - maxLength: 50)
    • middle_name: (string - maxLength: 50)
    • primary_address: required(object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • address_line3: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: required(string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • title: (string - maxLength: 50)
    • passport: (object)
      • passport_number: required(string - maxLength: 10)
      • passport_expiry: required(datetime)

        passport expiration date; must be later than current date

      • passport_issuing_country: required(string)

        ISO 3166 Alpha-3 country code

    • date_of_birth: required(datetime)
    • last_name: required(string)
    • email_address: required(string)

      client email address; must be a valid email addresss.

  • bpay_reference_number: (string)
  • account_id: required(string)

    The External Account Id (EAID)

  • name_on_card: (string)

    The cardholder name engrossed on the physical card

  • bpay_biller_code: (string)
  • portal_identifier: (object)

    The portal identifier associated with this account.

    • client_id: required(string)

      the client id assigned to the account

    • program_id: required(string)

      the program id assigned to the account

    • cardholder_id: required(string)

      the cardholder id assigned to the account

  • product_type: required(one of reloadable, gift, loyalty)
  • company_id: required(integer)

    The company id

  • balance: required(number)

    The balance of the account.

  • is_plastic_enabled: required(boolean)

    The plastic_enabled flag. Either true or false.

  • is_compliant: (boolean)
  • status: required(one of active, pre_active, inactive, deactivated, lost_or_stolen, expired, suspected_fraud, closed, inactive_pin_tries_exceeded, eml_inactive, replaced)

    The status of the account.

  • plastic_expiry: required(datetime)

    The plastic expiration date

  • card_number: required(string)

    The masked credit card number

  • external_account_id: required(string)

    The external reference id

  • display_name: (string)

    The client-supplied display name for the account. For salary packaging, this will include the employer name and benefit type.

  • account_expiry: required(datetime)

    The account expiration date

  • direct_entry_bsb: (string)
  • free_text: (object)

    The free text information for the account holder.

    • free_text4: required(string)
    • free_text6: required(string)
    • free_dec2: required(string)
    • free_text8: required(string)
    • free_text7: required(string)
    • free_text5: required(string)
    • free_text1: required(string)
    • free_int2: required(string)
    • free_text3: required(string)
    • free_int1: required(string)
    • free_text2: required(string)
    • free_dec1: required(string)

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

update account details

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • client_account_key: (string - maxLength: 255)

    the client account key for salary packaging programs; valid characters are within the range of ASCII code 0x20 and 0x7E inclusive

  • display_name: (string - maxLength: 100)

    the display name for FBT card program

  • initiating_user_id: (string)

    the user who initiated this request

  • registration: required(object)

    the client details including name, address and passport

    • driver_licence_number: (string - maxLength: 30)
    • alternate_address: (object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: (string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • first_name: required(string - maxLength: 50)
    • phone_number: (string - maxLength: 50)
    • sex: required(string)

      client gender; must be either 'M' or 'F'

    • mobile_number: (string - maxLength: 50)
    • middle_name: (string - maxLength: 50)
    • primary_address: required(object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • address_line3: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: required(string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • title: (string - maxLength: 50)
    • passport: (object)
      • passport_number: required(string - maxLength: 10)
      • passport_expiry: required(datetime)

        passport expiration date; must be later than current date

      • passport_issuing_country: required(string)

        ISO 3166 Alpha-3 country code

    • date_of_birth: required(datetime)
    • last_name: required(string)
    • email_address: required(string)

      client email address; must be a valid email addresss.

  • portal_identifier: (object)

    The portal identifier associated with this account.

    • client_id: required(string)

      the client id assigned to the account

    • program_id: required(string)

      the program id assigned to the account

    • cardholder_id: required(string)

      the cardholder id assigned to the account

Example:

{
  "display_name": "test user",
  "client_account_key": "client account 1",
  "registration": {
    "first_name": "test",
    "last_name": "user",
    "email_address": "[email protected]",
    "primary_address": {
      "address_line1": "test address",
      "country": "AU",
      "state": "QLD"
    },
    "passport": {
      "passport_issuing_country": "AUS",
      "passport_expiry": "2020-10-31T01:00:00Z",
      "passport_number": "abc"
    },
    "sex": "M",
    "date_of_birth": "2000-10-01T01:00:01Z"
  },
  "initiating_user_id": "testuser"
}

HTTP status code 200

The operation was successful, and the account was updated successfully

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support. Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

get

get

Get transaction history for the account

Get transaction history for the account

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Query Parameters

  • start_date: (datetime)

    Return transactions not before the specified date. The date is in ISO 8601 UTC format. For example: 2018-02-24T09:02:10Z

  • end_date: (datetime)

    Return transactions no later than the specified date. The date is in ISO 8601 UTC format. For example: 2018-02-24T09:02:10Z

  • page_number: required(string)

    The page number to retrieve. Valid values are between 1 and X-TotalPages inclusive. (see response headers for more information)

  • page_size: required(string)

    The number of records to retrieve in each page. There may be an internal minimum and maximum for this value. The X-PageSize header on the response shows which page size was applied.

HTTP status code 200

The operation was successful, and the transaction history items are presented in the response.

Headers

  • X-PageSize: required(number)

    The size of each page in the result set. May differ from the page_size in the query string if the size requested was smaller than the minimum or larger than the maximum.

  • X-TotalPages: required(number)

    The total number of pages in the result set.

  • X-TotalItems: required(number)

    The total number of records in the result set.

Body

Media type: application/vnd.eml+json

Type: array of object

Items: TransactionHistoryItem

  • amount: required(number)

    The base value of the transaction. Generally, the amount which was charged at POS or was withdrawn from an ATM.

  • running_balance_amount_currency: required(string)

    The ISO 4217 alphabetic code of the currency of the running balance amount. Currently only AUD.

  • type_description: required(string)

    The transaction type description.

  • account_id: required(string)

    The external account id (EAID) for the account which performed this transaction.

  • occurred_at: required(string)

    The date/time of the transaction in ISO 8601 format. Expect the timezone to be in UTC.

  • type: required(string)

    The four digit transaction type code for this transaction.

  • fee_amount_currency: required(string)

    The ISO 4217 alphabetic code of the currency of the fee amount. Currently only AUD.

  • amount_currency: required(string)

    The ISO 4217 alphabetic code of the currency of the transaction amount. Currently only AUD.

  • running_balance_amount: required(number)

    The running balance of the account as a result of this transaction.

  • card_acceptor_id: required(string)

    The card acceptor (merchant) identifier for this transaction.

  • reference: required(string)

    The reference data of this transaction.

  • parent_id: required(string)

    The identifier of the parent transaction, if applicable.

  • id: required(string)

    The identifier of this transaction.

  • terminal_id: required(string)

    The terminal identifier for this transaction.

  • merchant_category_code: required(string)

    The ISO 18245 four digit code identifying the category of the merchant.

  • acquirer_id: required(string)

    The acquirer identifier for this transaction.

  • fee_amount: required(number)

    The value of any fees which were applied to this transaction.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

get put

get

This is a light-weight version of GetAccountDetails that simply returns the balance and card state for a card

put

Updates the status of the account

This is a light-weight version of GetAccountDetails that simply returns the balance and card state for a card

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • balance: required(number)

    The balance of the account.

  • card_number: required(string)

    The masked credit card number

  • company_id: required(integer)

    The company id

  • external_account_id: required(string)

    The external reference id

  • plastic_expiry: required(datetime)

    The plastic expiration date

  • product_type: required(one of reloadable, gift, loyalty)
  • status: required(one of active, pre_active, inactive, deactivated, lost_or_stolen, expired, suspected_fraud, closed, inactive_pin_tries_exceeded, eml_inactive, replaced)

    The status of the account.

  • is_plastic_enabled: required(boolean)

    The plastic_enabled flag. Either true or false.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support. Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

Updates the status of the account

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • status: required(one of active, pre_active, inactive, deactivated, lost_or_stolen, expired, suspected_fraud, inactive_pin_tries_exceeded, eml_inactive, closed, replaced)

Example:

{
  "status": "active"
}

HTTP status code 200

The operation was successful, and the account status has been updated.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Perform an encrypted exchange of DIP data

Perform an encrypted exchange of DIP data

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • application_id: required(string)

    The UUID which identifies the requesting application.

  • key_id: required(string)

    The UUID which identifies application key in use by the consuming application.

  • ephemeral_key: required(string)

    A random, single-use, 256-bit (32 byte) value, encoded as a Base64 string.

Example:

{
  "application_id": "4bdb92b7-e22e-4012-aed4-9276ec67ead7",
  "key_id": "d7d5b030-e94f-43f7-942d-3d6703236b84",
  "ephemeral_key": "pwmbH/7quy8Jo0YtcPqz8oRqD53WCa4cHDaKkYueBLk="
}

HTTP status code 200

The operation was successful, and the encrypted DIP data is enclosed in the response body. See the DIP documentation for more info.

Body

Media type: application/octet-stream

Type: string

HTTP status code 400

Your request was invalid. Correct your request and try again.

Possible error codes:

  • bad_application_id
  • bad_key_id
  • bad_ephemeral_key
  • bad_account

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Perform Direct Entry Out tranfer

Perform Direct Entry Out tranfer

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • initiating_user_id: (string)

    the user who initiated this request.

  • request_id: (string - maxLength: 100)

    user provided id for tracking Direct Entry Out transfer transaction. Request with requested_id set will be cached for 30 days. If a transfer is handled successfully, any following request with the same request_id will be delivered the same cached response.

  • amount: required(number)

    the amount to be transfered. Ths must be positive.

  • source_reference: required(string - maxLength: 75)
  • destination_reference: required(string - maxLength: 75)
  • destination_account_info: required(object)
    • bsb: required(string)

      6 digit BSB number.

    • account_number: required(string)

      account number; only digits 0-9 are allowed.

    • account_name: required(string)

HTTP status code 200

The operation was successful.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • transaction_id: required(integer)

    transaction id returned by EML.

  • correlation_id: required(string)

    correlation id for troubleshooting.

HTTP status code 400

Your request was invalid. Correct your request and try again.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Perform Card to card tranfer

Perform Card to card tranfer

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • initiator_username: (string)

    the user who initiated this request.

  • request_id: (string - maxLength: 100)

    user provided id for tracking Card to Card transfer transaction. Request with requested_id set will be cached for 30 days. If a transfer is handled successfully, any following request with the same request_id will be delivered the same cached response.

  • amount: required(number)

    the amount to be transfered. Ths must be positive.

  • source_reference: required(string - maxLength: 75)
  • destination_reference: required(string - maxLength: 75)
  • destination_account_id: required(string)

    the external account id of the destination account

  • transaction_type: required(integer)

    2950 for EpayLoad and others for Card to Card transfer.

HTTP status code 200

The operation was successful.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • transaction_id: (integer)

    transaction id returned by EML; this field is empty if anything goes wrong

  • correlation_id: required(string)

    correlation id for troubleshooting.

HTTP status code 400

Your request was invalid. Correct your request and try again.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

put

put

Updates the plasticEnalbed flag of the account

Updates the plasticEnalbed flag of the account

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • plastic_enabled: required(boolean)
  • initiating_user_id: (string)

Example:

{
"initiating_user_id":"test user",
"plastic_enabled": false
}

HTTP status code 200

The operation was successful, and the plasticEnalbed flag has been updated.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Get Samsung, Google and Apple pay Wallet Data for account.

Get Samsung, Google and Apple pay Wallet Data for account.

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

  • provider: required(string)

    The Wallet Provider. Supported providers include Samsung, Google and Apple.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • token_unique_reference: (string)
  • initiating_user_id: (string)
  • nonce: required(string)

    Nonce field for ApplePay. Required for ApplePay, ignored in other wallet

  • nonce_signature: required(string)

    NonceSignature field for ApplePay. Required for ApplePay, ignored in other wallet

  • certificates: required(array of string)

    Certificates field for ApplePay. Required for ApplePay, ignored in other wallet

HTTP status code 200

The operation was successful.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • pan_last_four: required(string)
  • provider: required(one of mastercard, visa)
  • pruduct_type: required(one of reloadable, gift, loyalty)
  • registration: required(object)
    • driver_licence_number: (string - maxLength: 30)
    • alternate_address: (object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: (string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • first_name: required(string - maxLength: 50)
    • phone_number: (string - maxLength: 50)
    • sex: required(string)

      client gender; must be either 'M' or 'F'

    • mobile_number: (string - maxLength: 50)
    • middle_name: (string - maxLength: 50)
    • primary_address: required(object)
      • address_line1: (string - maxLength: 50)
      • address_line2: (string - maxLength: 50)
      • address_line3: (string - maxLength: 50)
      • city: (string - maxLength: 50)

        city or suburb. This is the REST equivalent of suburb field in ClientDetails of SOAP interface

      • state: required(string - maxLength: 6)
      • country: required(string)

        ISO3166 Alpha-2 country code

      • postcode: (string - maxLength: 30)

        postcode in alphanumeric characters

    • title: (string - maxLength: 50)
    • passport: (object)
      • passport_number: required(string - maxLength: 10)
      • passport_expiry: required(datetime)

        passport expiration date; must be later than current date

      • passport_issuing_country: required(string)

        ISO 3166 Alpha-3 country code

    • date_of_birth: required(datetime)
    • last_name: required(string)
    • email_address: required(string)

      client email address; must be a valid email addresss.

  • issuer_initiated_digitization_data: required(string)

    Mastercard issuerInitiatedDigitizationData. Required for Samsung and Google Pay

  • activation_data: required(string)

    ApplePay ActivationData. Required for ApplePay

  • encrypted_pass_data: required(string)

    ApplePay EncryptedPassData. Required for ApplePay

  • ephemeral_public_key: required(string)

    ApplePay EphemeralPublicKey. Required for ApplePay

HTTP status code 404

The supplied provider was invalid or input parameters validation error.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support. Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

get

get

Get all moble wallet tokens associated with the account

Get all moble wallet tokens associated with the account

Secured by

URI Parameters

  • id: required(string)

    The External Account Id (EAID) of the account.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: array of object

Items: WalletToken

  • storage_technology: required(one of unknown, device_memory, device_memory_protected_by_tpm, server, trusted_execution_environment, secure_element, virtual_execution_environment)

    The architecture or technology used for token storage.

  • device: required(object)

    device type defined by Mastercard.

    • device_id: (string)

      Serial number of the device provisioned with the token. May be masked.

    • device_name: (string)

      Nickname of the device provisioned with the token.

    • secure_element_id: (string)

      Identifier of the secure element provisioned with the token.

    • device_type: (one of unknown, watch1, smartphone_with_fixed_secure_element, tablet_or_ereader_with_fixed_secure_element, smartphone_with_payment_app_in_host_processor, tablet_or_ereader_with_payment_app_in_tee, watch_with_payment_app_in_tee, watch_with_payment_app_in_host_processor, phone, tablet, watch2, sticker, personal_computer, device_peripheral, tag, jewelry, fashion_accessory, garment, domestic_appliance, vehicle, media_or_gaming_device, undefined)

      Type of the device provisioned with the token.

  • last_comment_id: required(string)

    Identifier of the last comment associated with the token.

  • token_type: required(one of unknown, embedded_secure_element_token, master_card_cloud_based_payments_token, cof_token)
  • payment_app_instance_id: (string)

    Identifier of the Payment App instance within a device that will be provisioned with a token.

  • wallet_id: (string)

    Identifier of the Wallet Provider who requested the digitization or tokenization.

  • token_requestor_name: (string)

    The legal name of the token requestor. There can be more than one Token Requestor Id per Token Requester Name (legal name). So it is important to use both parameters to uniquely identify a token requestor. String, up to 100 characters.

  • token_assurance_level: required(string)

    Indicates the level of Identification and Verification performed to validate the Cardholder and the Cardholder's account at the time the Token was issued (or at any subsquent time post-issuance). Only present when a token has a Token Assurance Level assigned. Supported values are 0 (Not Authenticated) and non-zero (Authenticated).

  • token_requestor_id: required(string)

    Per EMV Co, the entity uniquely recognized by Mastercard as the Token Service Provider. String, up to 11 characters.

  • provisioning_status_description: (string)

    Description of the provisioning statu.

  • provisioning_status_code: (one of unknown, token_being_prepared, awaiting_cardholder_tc_acceptance, token_being_delivered, awaiting_activation, success, failed)

    Current provisioning status of the token.

  • suspenders: (array of string)

    Suspender(s) of the token when the token current status is SUSPENDED.

  • current_status_date_time: required(datetime)

    Date and time the status was updated. string, ISO 8601 format – YYYY-MM-DDThh:mm:ssTZD

  • current_status_code: required(one of unknown, unmapped, active, suspended, deleted)

    Current status of the Token.

  • correlation_id: (string)

    Value linking pre-digitization messages generated during provisioning.

  • activation_code_expiration_date_time: (datetime)

    Date and time when an Activation Code will expire.

  • final_tokenization_decision: (one of unknown, digitisation_declined, digitisation_approved, digitisation_approved_prior_authentication_required)

    Final decision related to the digitization of the Account PAN for this token.

  • token_activated_date_time: (datetime)

    Date and time that the token was activated.

  • digitization_request_date_time: (datetime)

    Date and time of the initial request for digitization of the Account PAN for this token.

  • account_pan_sequence_number: required(string)

    The Account PAN Sequence Number associated with a specific token, as provided to MDES previously by the issuer. It may be used to distinguish between multiple cardholders for a single Account PAN, to represent an issuance number of a specific card, or to distinguish between different card products, such as debit or credit, that share the same Account PAN. Conditional field, present when successfully assigned. 3 characters in length, max. Supported values - 000 to 099.

  • expiration_date: required(string)

    Expiration date of token. Conditional field, present once the token has been designated for the digitization. Four digit string. Format "mmyy".

  • token_suffix: (string)

    Last 4 digits of token in a 4 character string

  • primary_account_number_unique_reference: (string)

    Unique reference to the Account PAN originally digitized. Conditional field, present when successfully assigned.

  • token_unique_reference: required(string)

    A unique reference assigned following the allocation of a token used to identify the token for the duration of its lifetime. Conditional field, present when successfully assigned. 48 character string.

  • current_status_description: required(string)

    Description of the current status.

  • token_deleted_from_consumer_app: required(boolean)

    ndicates whether or not a token has been deleted from the consumer app by the token requestor.

HTTP status code 404

The supplied account_id was invalid or could not be found.

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

HTTP status code 500

An internal server error occurred. Try again soon, or contact support. Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

/funding

post

post

Post a new redemption transaction

Post a new redemption transaction

Secured by

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • amount: required(number)

    The value of the redemption.

  • account_id: required(string)

    The External Account Id (EAID) of the account to attempt the transaction on.

  • funding_exception: required(no_exception restrictions_not_satisfiable funding_exhausted)

    For an advice message which fails funding requirements, this property indicates which exception category the transaction will fall in to.

  • merchant_name_location: required(string)

    The Card Acceptor Name and Location, mapped from DE 43.

  • originating_transaction: required(number)

    The Transaction Id (Sequence Number) of the proxy card transaction which led to this request.

  • clearing_adjustment: required(boolean)

    Indicates if this redemption is the result of a clearing adjustment.

  • currency: required(string)

    The ISO 4217 numeric currency code of the transaction.

  • card_acceptor_id: required(string)

    The Alphanumeric Id for the merchant, mapped from DE 42.

  • correlation_id: required(string)

    A unique identifier, generated by you, for the originating transaction (i.e. the proxy card transaction).

  • merchant_category: required(string)

    The 4-digit merchant category code

  • terminal_id: required(string)

    The Alphanumeric Id for the terminal, mapped from DE 41.

  • acquirer_id: required(string)

    The numeric Id for the acquirer, mapped from DE 32.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • outcome: required(approved declined)

    The outcome of the request, either approved or declined.

  • transaction_id: (number)

    A unique identifier for the successful authorization request. Not present if the outcome is declined.

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Post a new reversal transaction

Post a new reversal transaction

Secured by

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • account_id: required(string)

    The External Account Id (EAID) of the account to attempt the transaction on.

  • originating_transaction: required(number)

    The Transaction Id (Sequence Number) of the proxy card transaction which led to this request.

  • correlation_id: required(string)

    A unique identifier, generated by you, for the originating transaction (i.e. the proxy card transaction).

  • parent_transaction_id: required(number)

    The id of the redemption which is being reversed. This should match the transaction_id property of a response you received from us previously on the /authorizations/redemptions endpoint for this account.

  • clearing_adjustment: required(boolean)

    Indicates if this reversal is the result of a clearing adjustment.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • outcome: required(approved declined)

    The outcome of the request, either approved or declined.

  • transaction_id: (number)

    A unique identifier for the successful authorization request. Not present if the outcome is declined.

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by

post

post

Post a new refund transaction

Post a new refund transaction

Secured by

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • amount: required(number)

    The value to credit to the account.

  • account_id: required(string)

    The External Account Id (EAID) of the account to attempt the transaction on.

  • parent_transaction_id: (number)

    The transaction_id of a parent transaction, if one was identified.

  • merchant_name_location: required(string)

    The Card Acceptor Name and Location, mapped from DE 43.

  • originating_transaction: required(number)

    The Transaction Id (Sequence Number) of the proxy card transaction which led to this request.

  • currency: required(string)

    The ISO 4217 numeric currency code of the transaction.

  • card_acceptor_id: required(string)

    The Alphanumeric Id for the merchant, mapped from DE 42.

  • correlation_id: required(string)

    A unique identifier, generated by you, for the originating transaction (i.e. the proxy card transaction).

  • merchant_category: required(string)

    The 4-digit merchant category code

  • terminal_id: required(string)

    The Alphanumeric Id for the terminal, mapped from DE 41.

  • acquirer_id: required(string)

    The numeric Id for the acquirer, mapped from DE 32.

HTTP status code 200

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • outcome: required(approved declined)

    The outcome of the request, either approved or declined.

  • transaction_id: (number)

    A unique identifier for the successful authorization request. Not present if the outcome is declined.

HTTP status code 500

An internal server error occurred. Try again soon, or contact support.

Possible error codes:

  • server_error

Body

Media type: application/vnd.eml+json

Type: object

Properties
  • error: required(string)
  • error_description: (string)

Secured by