NAV Navbar

BankEngine

Introduction

BankEngine allows you to connect to your end users bank, to securely initiate payments or read their financial data which includes balances, transactions and accounts.

We provide a simple unified API interface to all banks in New Zealand.

Getting Started

  1. Email us to obtain your client_id and client_secret. You will need to supply us with at least one redirect_uri.

  2. Generate an authentication link to redirect your users too.

  3. Obtain an access_token following the authentication flow.

  4. Use the API to retrieve end user’s personal information, account numbers, transaction data and make payments.

Access Methods

BankEngine uses the following methods to access APIs from providers:

Open Banking: We use Payments NZ Open Banking API's for all available providers. The authentication flow is managed by the bank.

Direct Connection: BankEngine accesses private bank API's when Open Banking API's are not available. We use methods that never store the users credentials. All authentication data for users is encrypted in-place and at-rest.

Versioning

Stable endpoints will not have any breaking changes before the beta release.

Definitions

DEFINITION DESCRIPTION
Account A bank account with a provider
Authorization Server A spec compliant OAuth 2.0 server hosted by BankEngine that allows end users to authenticate with their provider credentials. It also offers API endpoints to inspect, get and renew access tokens.
Client An application accessing this API
User An application’s user and the owner of an account
API The API that provides access to end users bank data
Permissions A set of permissions the end user can grant to a client application. Each API resource in BankEngine is protected by a permission.
Provider A supported bank or other financial institution
Credentials A set of identifiers and secrets the end user uses to access their accounts with a provider

Authentication

To use any of BankEngine API's you must generate an access token. An access token represents access to a single provider for an end user. Calling any of BankEngine APIs without a valid access token will return an unauthorized exception.

Overview

  1. Redirect the user in a browser to the BankEngine authorization server. The authorization link will contain your client_id, a redirect_uri, permissions requested, an nonce and state.

  2. The user will accept review the permissions requested and accept the BankEngine end user terms of service.

  3. The user will select their provider from a list of supported providers.

  4. The user will authenticate with the provider.

  5. BankEngine will redirect back to your redirect_uri, with a one time authorization code and the state parameter.

  6. The client application will call our exchange token authorization endpoint to swap the code with an access_token.

  7. The client application will now be able to call the BankEngine API.

Authentication Definitions

IDENTIFIER DESCRIPTION
access_token JWT which represents access to a user at a provider
client_id Unique identifer that identifies a Client
client_secret Secret used to authenticate a Client
code Single use code that is exchanged for an access_token
redirect_uri URI that authorization server will redirect the Client to
refresh_token A token used to obtain a new access_token

User Authentication

 https://auth.bankengine.nz/connect/authorize\
  ?response_type=code\
  &client_id=${client_id}\
  &redirect_uri=${redirect_uri}\
  &scope=${scope}\
  &state=${state}

Redirect the user in a browser to the BankEngine authorization server.

PARAMETER DESCRIPTION
client_id Unique identifer that identifies a Client
redirect_uri URI that authorization server will redirect the Client to
scope A space seperated list of permissions requested
state A unique value associated with each authentication request to be verified in the redirect

Code redirect

End user’s browser is redirected to perform an HTTP GET to the redirect_uri controlled by the Client with the following parameters:

Parameters

PARAMETER DESCRIPTION
code Single use code that is exchanged for an access_token
state A unique value associated with each authentication request

Exchange code with access_token

Request

curl -X POST \
    -d grant_type=authorization_code \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d redirect_uri=${redirect_uri} \
    -d code=${code} \
    https://auth.bankengine.nz/connect/token

Parameters

PARAMETER DESCRIPTION
client_id Unique identifer that identifies a Client
client_secret Secret used to authenticate a Client
code Single use code that is exchanged for an access_token
grant_type "authorization_code"
redirect_uri Only the redirect_uri that was registered with the client is accepted.

Response

Response

{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "..."
}

The Authorization server will respond with JSON

PARAMETER DESCRIPTION
access_token JWT which represents access to a user at a provider
expire_in How long an access token is valid for in seconds, default is 1 hour.
refresh_token Only returned if offline_access scope if requested. Can be used to refresh an access token.
token_type "Bearer"

Refresh token

Request

curl -X POST \
    -d grant_type=refresh_token \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d refresh_token=${refresh_token} \
    https://auth.bankengine.nz/connect/token

Parameters

PARAMETER DESCRIPTION
client_id Unique identifer that identifies a Client
client_secret Secret used to authenticate a Client
refresh_token Single use token to be used to refresh an access token
grant_type "refresh_token"

Response

Response

{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "..."
}

The Authorization server will respond with JSON

PARAMETER DESCRIPTION
access_token JWT which represents access to a user at a provider
expire_in How long an access token is valid for in seconds, default is 1 hour.
refresh_token Only returned if offline_access scope if requested. Can be used to refresh an access token.
token_type "Bearer"

Permissions

An Authentication Link must include a set of permissions in the scope parameter that your Client is requesting on behalf of the End user. These permissions (or scopes) limit what endpoints the Client will be authorized to access in the Data API.

SCOPE DESCRIPTION API ENDPOINT
userinfo Access user’s identity information /identity/v0/userinfo
accounts Access user's account information /data/v1/accounts, /data/v1/accounts/${account_id}
accounts + balance Access user's account balance /data/v1/accounts/${account_id}/balance
accounts + transactions Access user's transactions /data/v1/accounts/${account_id}/transactions
payments Create payments from a users' account /payments/v0/payment/
offline_access Allows access to End user’s data after the short-lived access_token expires. When this permission is granted a refresh_token will be returned

Errors

Response

{
    "error":  "internal_error",
    "description": "Well, this is embarrassing!"
}
Field Name Description
error An error code
description Details about the error

API

Identity v0

Retrieve identity information

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.bankengine.nz/identity/v0/userinfo

Response

{
    "data": [
        {
            "addresses": [
                {
                    "address": "53 Hurstmere Road",
                    "city": "Auckland",
                    "country": "NZ",
                    "postCode": "0620"
                }
            ],
            "dateOfBirth": "1994-03-13T00:00:00",
            "emails": [
                "hello@bankengine.nz"
            ],
            "fullName": "John Smith",
            "phones": [
                "+6494894427"
            ],
            "update_timestamp": "0001-01-01T00:00:00Z"
        }
    ]
}

Returns End user’s identity information held by the Provider. This can include name, address, emails and phone numbers.

Data v1

Get all accounts

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.bankengine.nz/data/v1/accounts

Response

{
    "data": [
        {
            "accountId": "0cab7394805b8658",
            "accountType": "transactional",
            "accountNumber": "01-0178-00132944-00",
            "currency": "NZD",
            "displayName": "Go Money",
            "updateTimestamp": "0001-01-01T00:00:00Z",
            "provider": {
                "providerId": "anz",
                "displayName": "ANZ Bank"
            },
            "links" : {
                "self": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658",
                "balances": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658/balance",
                "transactions": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658/transactions"
            }
        },
        {
            "accountId": "045709fa919f7fbe",
            "accountType": "savings",
            "accountNumber": "01-0178-00132944-50",
            "currency": "NZD",
            "displayName": "Serious Saver",
            "updateTimestamp": "0001-01-01T00:00:00Z",
            "provider": {
                "providerId": "anz",
                "displayName": "ANZ Bank"
            },
            "links" : {
                "self": "https://api.bankengine.nz/data/v1/accounts/045709fa919f7fbe",
                "balances": "https://api.bankengine.nz/data/v1/accounts/045709fa919f7fbe/balance",
                "transactions": "https://api.bankengine.nz/data/v1/accounts/045709fa919f7fbe/transactions"
            }
        }
    ]
}

Returns all End user’s accounts and associated data

Get a single account

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.bankengine.nz/data/v1/accounts/${account_id}
{
    "data": [
        {
            "accountId": "0cab7394805b8658",
            "accountType": "transactional",
            "accountNumber": "01-0178-00132944-00",
            "currency": "NZD",
            "displayName": "Go Money",
            "updateTimestamp": "0001-01-01T00:00:00Z",
            "provider": {
                "providerId": "anz",
                "displayName": "ANZ Bank"
            },
            "links" : {
                "self": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658",
                "balances": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658/balance",
                "transactions": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658/transactions"
            }
        }
    ]
}

Returns data associated with the specified account_id

Get account balance

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.bankengine.nz/data/v1/accounts/${account_id}/balance

Response

{
    "data": [
        {
            "currency": "NZD",
            "available": 717.92,
            "current": 717.92,
            "overdraft": 0,
            "updatedTimestamp": "2019-08-25T03:19:58.5350558Z",
            "links": {
                "self": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658/balance",
                "account": "https://api.bankengine.nz/data/v1/accounts/0cab7394805b8658"
            }
        }
    ]
}

Returns balance information for the specified account_id

Retrieve account transactions

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.bankengine.nz/data/v1/accounts/${account_id}/transactions?from=${from}&to=${to}"
{
    "data": [
        {
            "transactionId": "0785258dac9a3bd0",
            "timestamp": "2019-08-23T00:00:00",
            "description": "Uber Eats He Card number: 1234 **** **** 1234",
            "amount": -23.99,
            "currency": "NZD",
            "status": "posted",
            "creditDebitIndicator" : "debit",
            "type": "debit card",
            "categories": [
                "food"
            ],
            "merchantName": "Uber Eats"
        },
        {
            "transactionId": "ffb0635a4384a574",
            "timestamp": "2019-08-23T00:00:00",
            "description": "From: 01-0178-00132944-00 Credit Transfer 125618",
            "amount": 1000,
            "currency": "NZD",
            "status": "posted",
            "creditDebitIndicator" : "credit",
            "type": "transfer",
            "categories": []
        },
        {
            "transactionId": "794117638b94050f",
            "timestamp": "2019-08-23T00:00:00",
            "description": "John S Rent",
            "amount": -400,
            "currency": "NZD",
            "status": "posted",
            "creditDebitIndicator": "debit",
            "type": "bill payment",
            "categories": [
                "rent"
            ]
        }
    ]
}

Returns transaction data for the specified account_id.

Payments v0

Create a single payment

curl -X POST \
  https://api.bankengine.nz/payments/v0/payment \
  -H "Authorization: Bearer ${access_token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "fromAccount": "01-0178-00132944-00",
    "toAccount": "01-3846-1292687-50",
    "from" : {
        "particulars" : "tfr-saving",
        "code" : "",
        "reference": ""
    },
    "to" : {
        "particulars" : "tfr-saving",
        "code" : "",
        "reference": ""
    },
    "amount": 10.00
}'