Welcome
API Docs
AccountsCategoriesTagsTransactionsUtility endpointsWebhooks
Get HelpPartnerships RoadmapCareersBlogAcceptable Use Policy
API Beta Release
Let's Hack On Banking Together
Calling all makers, creators, hackers, and hobbyists.
Welcome to the first stage of Up’s API: a beta release that gives you programmatic access to your balances and transaction data. You can request past transactions or set up webhooks to receive real time events when new transactions hit your account. It’s new, exciting and just the beginning.
This time it's personal
This first phase of the API is designed to give you (and only you) access to your personal data. Get a Personal Access Token that can then be used to make secure requests from our API. Read the docs below to see what you can ask for and the sorts of responses you can expect. In the future we’ll be expanding our API to allow developers to create applications or integrations other customers can use.
Getting started with our API
Before you start
It’s true, working with an API is going to require some programming knowledge. It also helps to be familiar with a console/terminal. In the examples below we’re going to provide terminal commands you can run on your computer. It doesn’t really matter what programming language you choose, but if you don’t yet know any, consider Rails or Javascript. There’s a ton of online material available to help you learn and great communities to join.
Sign-up if you're not a customer

It takes just a couple of steps to get up and running. If you’re not yet an Upsider the first thing you’ll need to do is sign up here: https://up.com.au/download/. Great! Let’s go to the next step.

Rotating logo
Claim your Personal Access Token

Your personal access token is the key to your financial kingdom. Guard it fiercely and never share it online or give it out. If you are worried it may have fallen into the wrong hands it’s easy to generate a new one (and expire the old one) - see below.

Steps to claim

1. Go to https://api.up.com.au (or tap the Personal Access Token button in the top right) in a web browser. This must be done on a tablet or computer.

2. Open the Up app on your mobile, swipe right and select "Scan QR Code".

3. Scan the QR code displayed on the webpage.

4. Presto! You now have a Personal Access Token. Copy this and store it safely.

Reissuing your Personal Access Token

It’s better to be safe than sorry. If, for any reason, you’re worried about the safety of your Personal Access Token follow these very simple steps to generate a new one.

1. Follow the instructions above to log in to https://api.up.com.au.

2. You should now be looking at your access token – simply click the refresh button to generate a new one. Your old token will immediately stop working.

Rotating logo
Make your first API Request

Ok let's get our hands dirty! The simplest request in the book is to first verify that your token works.

Verify the access token

To test your access token, make a request to the /util/ping endpoint. You'll need to put your access token in the Authorization header like so:

Authorization: Bearer $your_access_token

You should get a JSON response with a HTTP 200 status.

Sample Request

curl https://api.up.com.au/api/v1/util/ping \
-H "Authorization: Bearer $your_access_token"

Sample Response

{
"meta": {
"id": "3b5d17a4-6778-48dc-ae7d-9f8aace2e2fc",
"statusEmoji": "⚡️"
}
}

If the Authorization header is missing, is malformed, or contains an invalid access token, an error response will be returned with a HTTP 401 status.

URL Structure
The Up Banking API is versioned so that breaking changes can be made without impacting existing clients. The current version is v1 (beta). New endpoints will be added over time and existing endpoints will be extended. Some endpoints or fields within an endpoint may be deprecated, but nothing will be removed within any given version, in order to maintain backwards compatibility with existing clients.
Base URL

The endpoints documented in this reference must all be appended to the base URL before they can be called.

https://api.up.com.au/api/v1

For example, the GET /accounts endpoint is callable at

https://api.up.com.au/api/v1/accounts
Authentication
All requests to the Up Banking API must be authenticated by supplying an access token in the Authorization header. The bearer scheme is used to construct the Authorization header.

Sample Header

Authorization: Bearer $your_access_token
Personal access tokens
This access token is highly sensitive and must not be shared with other parties.

Currently the Up Banking API is only available for use with a personal access token, which can be obtained by visiting api.up.com.au and following the prompts.

Only one personal access token can be used at a time. Generating a new personal access token revokes any existing personal access tokens.

Many endpoints in the Up Banking API support pagination. When a endpoint supports pagination it includes a links field at the top-level of the response JSON and its data field contains an array of resources specific to the endpoint.

Sample Response

{
"data": [...],
"links": {
"prev": "https://api.up.com.au/api/v1/accounts?page[before]=x",
"next": "https://api.up.com.au/api/v1/accounts?page[after]=y"
}
}
The Up Banking API uses opaque cursors for pagination. Clients must refer to the prev and next links to move between pages.
Enumerating pages

On each page of results, the client consumes each of the resources contained in the data array. Forwards pagination is achieved by following the next link repeatedly until the next link is set to null . When the next link is null , there are no more pages available and pagination terminates. Backwards pagination is achieved by following the prev link repeatedly until the prev link is set to null . When the prev link is null , there are no more pages available and pagination terminates.

Specifying the page size

Endpoints that support pagination accept a page[size] query parameter. This value must be a positive integer and is generally constrained to an upper limit of 100 , however individual endpoints may impose different constraints.

Sample URL

https://api.up.com.au/api/v1/accounts?page[size]=10

When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint.

Error Responses
The Up Banking API uses HTTP status codes to convey success or failure when responding to requests. Success responses will always be in the 2xx range. Error responses will be in the usually be in the 4xx range, or more rarely, in the 5xx range.
Status Codes
200

Successful response: Everything worked as intended

201

Successful response: A new resource was created successfully—Typically used with POST requests.

204

Successful response: No content—typically used with DELETE requests.

400

Bad request: Typically a problem with the query string or an encoding error.

401

Not authorized: The request was not authenticated.

404

Not found: Either the endpoint does not exist, or the requested resource does not exist.

422

Invalid request: The request contains invalid data and was not processed.

429

Too many requests: You have been rate limited—try later, ideally with exponential backoff.

500 502 503 504

Server-side errors: Try again later.

When a response is received in the 4xx or 5xx range, it includes errors that should be referred for more detail.

Error Response

Generic error response that returns one or more errors.

errors

Array [ErrorObject]

The list of errors returned in this response.

status

string

The HTTP status code associated with this error. This can also be obtained from the response headers. The status indicates the broad type of error according to HTTP semantics.

title

string

A short description of this error. This should be stable across multiple occurrences of this type of error and typically expands on the reason for the status code.

detail

string

A detailed description of this error. This should be considered unique to individual occurrences of an error and subject to change. It is useful for debugging purposes.

source

object

(optional)

If applicable, location in the request that this error relates to. This may be a parameter in the query string, or a an attribute in the request body.

parameter

string

(optional)

If this error relates to a query parameter, the name of the parameter.

pointer

string

(optional)

If this error relates to an attribute in the request body, a rfc-6901 JSON pointer to the attribute.

Clients should typically convert these error responses to exceptions and handle them as necessary.

Accounts

Accounts represent the underlying store used to track balances and the transactions that have occurred to modify those balances over time. Up currently has two types of account: SAVER—used to earn interest and to hit savings goals, and TRANSACTIONAL—used for everyday spending.

List accounts
GET /accounts

Retrieve a paginated list of all accounts for the currently authenticated user. The returned list is paginated and can be scrolled by following the prev and next links where present.

Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30
Returns
200 - Successful Response
data

Array [AccountResource]

The list of accounts returned in this response.

type

string

The type of this resource: accounts

id

string

The unique identifier for this account.

attributes

object

displayName

string

The name associated with the account in the Up application.

accountType

AccountTypeEnum

The bank account type of this account.

balance

MoneyObject

The available balance of the account, taking into account any amounts that are currently on hold.

createdAt

string (date-time)

The date-time at which this account was first opened.

relationships

object

transactions

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/accounts \
-G \
-H 'Authorization: Bearer up:demo:2gL8KkZ1QBIqxflX' \
-d 'page[size]=1'

Sample Response

{
"data": [
{
"type": "accounts",
"id": "670b9cbd-b070-4da2-85fe-fc36804f496c",
"attributes": {
"displayName": "Up Account",
"accountType": "TRANSACTIONAL",
"balance": {
"currencyCode": "AUD",
"value": "1.00",
"valueInBaseUnits": 100
},
"createdAt": "2020-08-13T17:49:59+10:00"
},
"relationships": {
"transactions": {
"links": {
"related": "https://api.up.com.au/api/v1/accounts/670b9cbd-b070-4da2-85fe-fc36804f496c/transactions"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/accounts/670b9cbd-b070-4da2-85fe-fc36804f496c"
}
}
],
"links": {
"prev": null,
"next": "https://api.up.com.au/api/v1/accounts?page%5Bafter%5D=WyIyMDIwLTA4LTEzVDA3OjQ5OjU5LjQ3Mzg2MTAwMFoiLCI2NzBiOWNiZC1iMDcwLTRkYTItODVmZS1mYzM2ODA0ZjQ5NmMiXQ%3D%3D&page%5Bsize%5D=1"
}
}
Retrieve account
GET /accounts/{id}

Retrieve a specific account by providing its unique identifier.

Path Parameters
id

string

The unique identifier for the account.

e.g. 45075141-cc86-4b40-8c60-fa3b4250bf20
Returns
200 - Successful Response
data

AccountResource

The account returned in this response.

type

string

The type of this resource: accounts

id

string

The unique identifier for this account.

attributes

object

displayName

string

The name associated with the account in the Up application.

accountType

AccountTypeEnum

The bank account type of this account.

balance

MoneyObject

The available balance of the account, taking into account any amounts that are currently on hold.

createdAt

string (date-time)

The date-time at which this account was first opened.

relationships

object

transactions

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/accounts/7561ae7a-f2bb-4f05-b956-eda88c6f33d3 \
-H 'Authorization: Bearer up:demo:xlObUUaxfUMaquDv'

Sample Response

{
"data": {
"type": "accounts",
"id": "7561ae7a-f2bb-4f05-b956-eda88c6f33d3",
"attributes": {
"displayName": "Savings",
"accountType": "SAVER",
"balance": {
"currencyCode": "AUD",
"value": "125.36",
"valueInBaseUnits": 12536
},
"createdAt": "2020-08-13T17:50:00+10:00"
},
"relationships": {
"transactions": {
"links": {
"related": "https://api.up.com.au/api/v1/accounts/7561ae7a-f2bb-4f05-b956-eda88c6f33d3/transactions"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/accounts/7561ae7a-f2bb-4f05-b956-eda88c6f33d3"
}
}
}
Categories

Categories enable understanding where your money goes by driving powerful insights in Up. All categories in Up are pre-defined and are automatically assigned to new purchases in most cases. A parent-child relationship is used to represent categories, however parent categories cannot be directly assigned to transactions.

List categories
GET /categories

Retrieve a list of all categories and their ancestry. The returned list is not paginated.

Query Parameters
filter[parent]

string

The unique identifier of a parent category for which to return only its children. Providing an invalid category identifier results in a 404 Not Found response.

e.g. ?filter[parent]=good-life
Returns
200 - Successful Response
data

Array [CategoryResource]

The list of categories returned in this response.

type

string

The type of this resource: categories

id

string

The unique identifier for this category. This is a human-readable but URL-safe value.

attributes

object

name

string

The name of this category as seen in the Up application.

relationships

object

parent

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

children

object

data

Array [object]

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/categories \
-G \
-H 'Authorization: Bearer up:demo:tibMSxkGrtH44L2H' \
-d 'filter[parent]=good-life'

Sample Response

{
"data": [
{
"type": "categories",
"id": "hobbies",
"attributes": {
"name": "Hobbies"
},
"relationships": {
"parent": {
"data": {
"type": "categories",
"id": "good-life"
},
"links": {
"related": "https://api.up.com.au/api/v1/categories/good-life"
}
},
"children": {
"data": [],
"links": {
"related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=hobbies"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/categories/hobbies"
}
},
{
"type": "categories",
"id": "restaurants-and-cafes",
"attributes": {
"name": "Restaurants & Cafes"
},
"relationships": {
"parent": {
"data": {
"type": "categories",
"id": "good-life"
},
"links": {
"related": "https://api.up.com.au/api/v1/categories/good-life"
}
},
"children": {
"data": [],
"links": {
"related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=restaurants-and-cafes"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/categories/restaurants-and-cafes"
}
}
]
}
Retrieve category
GET /categories/{id}

Retrieve a specific category by providing its unique identifier.

Path Parameters
id

string

The unique identifier for the category.

e.g. restaurants-and-cafes
Returns
200 - Successful Response
data

CategoryResource

The category returned in this response.

type

string

The type of this resource: categories

id

string

The unique identifier for this category. This is a human-readable but URL-safe value.

attributes

object

name

string

The name of this category as seen in the Up application.

relationships

object

parent

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

children

object

data

Array [object]

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/categories/home \
-H 'Authorization: Bearer up:demo:jXc6xsnZPkvZm7vs'

Sample Response

{
"data": {
"type": "categories",
"id": "home",
"attributes": {
"name": "Home"
},
"relationships": {
"parent": {
"data": null
},
"children": {
"data": [
{
"type": "categories",
"id": "groceries"
}
],
"links": {
"related": "https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=home"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/categories/home"
}
}
}
Tags

Tags are custom labels that can be associated with transactions on Up. Within the Up application, tags provide additional insight into spending. For example, you could have a "Take Away" tag that you apply to purchases from food delivery services. The Up API allows you to manage the tags associated with transactions. Each transaction may have up to 6 tags.

Tags are identified by their labels, which are unique strings, so the tag "Holiday" has also the id "Holiday".

List tags
GET /tags

Retrieve a list of all tags currently in use. The returned list is paginated and can be scrolled by following the next and prev links where present. Results are ordered lexicographically. The transactions relationship for each tag exposes a link to get the transactions with the given tag.

Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=50
Returns
200 - Successful Response
data

Array [TagResource]

The list of tags returned in this response.

type

string

The type of this resource: tags

id

string

The label of the tag, which also acts as the tag’s unique identifier.

relationships

object

transactions

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/tags \
-G \
-H 'Authorization: Bearer up:demo:Fg0IJJ3EZbMjva4F' \
-d 'page[size]=2'

Sample Response

{
"data": [
{
"type": "tags",
"id": "Holiday",
"relationships": {
"transactions": {
"links": {
"related": "https://api.up.com.au/api/v1/transactions?filter%5Btag%5D=Holiday"
}
}
}
},
{
"type": "tags",
"id": "Pizza Night",
"relationships": {
"transactions": {
"links": {
"related": "https://api.up.com.au/api/v1/transactions?filter%5Btag%5D=Pizza+Night"
}
}
}
}
],
"links": {
"prev": null,
"next": "https://api.up.com.au/api/v1/tags?page%5Bafter%5D=WyJQaXp6YSBOaWdodCJd&page%5Bsize%5D=2"
}
}
Add tags to transaction
POST /transactions/{transactionId}/relationships/tags

Associates one or more tags with a specific transaction. No more than 6 tags may be present on any single transaction. Duplicate tags are silently ignored. An HTTP 204 is returned on success. The associated tags, along with this request URL, are also exposed via the tags relationship on the transaction resource returned from /transactions/{id}.

Path Parameters
transactionId

string

The unique identifier for the transaction.

e.g. 449e5367-f9bf-4fa5-ad1f-32fdfe289276
Request Payload
data

Array [TagInputResourceIdentifier]

The tags to add to or remove from the transaction.

type

string

The type of this resource: tags

id

string

The label of the tag, which also acts as the tag’s unique identifier.

Returns
204 - Successful Response

Sample Request

curl https://api.up.com.au/api/v1/transactions/2de31246-ef51-4669-ac5e-c635b92b8615/relationships/tags \
-XPOST \
-H 'Authorization: Bearer up:demo:wXvSWL9J5VsAKWCL' \
-H 'Content-Type: application/json' \
--data-binary '{
"data": [
{
"type": "tags",
"id": "Holiday"
},
{
"type": "tags",
"id": "Queensland"
}
]
}'
Remove tags from transaction
DELETE /transactions/{transactionId}/relationships/tags

Disassociates one or more tags from a specific transaction. Tags that are not associated are silently ignored. An HTTP 204 is returned on success. The associated tags, along with this request URL, are also exposed via the tags relationship on the transaction resource returned from /transactions/{id}.

Path Parameters
transactionId

string

The unique identifier for the transaction.

e.g. da7032b3-5cf7-4019-a09e-514e37c05ad0
Request Payload
data

Array [TagInputResourceIdentifier]

The tags to add to or remove from the transaction.

type

string

The type of this resource: tags

id

string

The label of the tag, which also acts as the tag’s unique identifier.

Returns
204 - Successful Response

Sample Request

curl https://api.up.com.au/api/v1/transactions/2752e950-29dc-4bb5-b8dc-a82a56af816c/relationships/tags \
-XDELETE \
-H 'Authorization: Bearer up:demo:5LL93FchfxBiGOv0' \
-H 'Content-Type: application/json' \
--data-binary '{
"data": [
{
"type": "tags",
"id": "Holiday"
},
{
"type": "tags",
"id": "Queensland"
}
]
}'
Transactions

Transactions represent the movement of money into and out of an account. They have many characteristics that vary depending on the kind of transaction. Transactions may be tempoarily HELD (pending) or SETTLED, typically depending on which payment method was used at the point of sale.

List transactions
GET /transactions

Retrieve a list of all transactions across all accounts for the currently authenticated user. The returned list is paginated and can be scrolled by following the next and prev links where present. To narrow the results to a specific date range pass one or both of filter[since] and filter[until] in the query string. These filter parameters should not be used for pagination. Results are ordered newest first to oldest last.

Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30
filter[since]

string

The start date-time from which to return records, formatted according to rfc-3339. Not to be used for pagination purposes.

e.g. ?filter[since]=2020-01-01T01:02:03+10:00
filter[until]

string

The end date-time up to which to return records, formatted according to rfc-3339. Not to be used for pagination purposes.

e.g. ?filter[until]=2020-02-01T01:02:03+10:00
filter[tag]

string

A transaction tag to filter for which to return records. If the tag does not exist, zero records are returned and a success response is given.

e.g. ?filter[tag]=Holiday
Returns
200 - Successful Response
data

Array [TransactionResource]

The list of transactions returned in this response.

type

string

The type of this resource: transactions

id

string

The unique identifier for this transaction.

attributes

object

status

TransactionStatusEnum

The current processing status of this transaction, according to whether or not this transaction has settled or is still held.

rawText

string

(nullable)

The original, unprocessed text of the transaction. This is often not a perfect indicator of the actual merchant, but it is useful for reconciliation purposes in some cases.

description

string

A short description for this transaction. Usually the merchant name for purchases.

message

string

(nullable)

Attached message for this transaction, such as a payment message, or a transfer note.

holdInfo

HoldInfoObject

(nullable)

If this transaction is currently in the HELD status, or was ever in the HELD status, the amount and foreignAmount of the transaction while HELD.

roundUp

RoundUpObject

(nullable)

Details of how this transaction was rounded-up. If no Round Up was applied this field will be null.

cashback

CashbackObject

(nullable)

If all or part of this transaction was instantly reimbursed in the form of cashback, details of the reimbursement.

amount

MoneyObject

The amount of this transaction in Australian dollars. For transactions that were once HELD but are now SETTLED, refer to the holdInfo field for the original amount the transaction was HELD at.

foreignAmount

MoneyObject

(nullable)

The foreign currency amount of this transaction. This field will be null for domestic transactions. The amount was converted to the AUD amount reflected in the amount of this transaction. Refer to the holdInfo field for the original foreignAmount the transaction was HELD at.

settledAt

string (date-time)

(nullable)

The date-time at which this transaction settled. This field will be null for transactions that are currently in the HELD status.

createdAt

string (date-time)

The date-time at which this transaction was first encountered.

relationships

object

account

object

data

object

type

string

The type of this resource: accounts

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

category

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

parentCategory

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

tags

object

data

Array [object]

links

object

(optional)
self

string

The link to retrieve or modify linkage between this resources and the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/transactions \
-G \
-H 'Authorization: Bearer up:demo:NxLwLWBnXDXTE9wr' \
-d 'page[size]=1' \
-d 'filter[tag]=Pizza Night'

Sample Response

{
"data": [
{
"type": "transactions",
"id": "0740d2fd-6a2f-431f-af7d-eb8f94899ef5",
"attributes": {
"status": "SETTLED",
"rawText": null,
"description": "David Taylor",
"message": "Money for the pizzas last night.",
"holdInfo": null,
"roundUp": null,
"cashback": null,
"amount": {
"currencyCode": "AUD",
"value": "-59.98",
"valueInBaseUnits": -5998
},
"foreignAmount": null,
"settledAt": "2020-08-12T10:48:12+10:00",
"createdAt": "2020-08-12T10:48:12+10:00"
},
"relationships": {
"account": {
"data": {
"type": "accounts",
"id": "337da758-fa4f-47f0-bae9-916a5ae01758"
},
"links": {
"related": "https://api.up.com.au/api/v1/accounts/337da758-fa4f-47f0-bae9-916a5ae01758"
}
},
"category": {
"data": null
},
"parentCategory": {
"data": null
},
"tags": {
"data": [
{
"type": "tags",
"id": "Pizza Night"
}
],
"links": {
"self": "https://api.up.com.au/api/v1/transactions/0740d2fd-6a2f-431f-af7d-eb8f94899ef5/relationships/tags"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/transactions/0740d2fd-6a2f-431f-af7d-eb8f94899ef5"
}
}
],
"links": {
"prev": null,
"next": null
}
}
Retrieve transaction
GET /transactions/{id}

Retrieve a specific transaction by providing its unique identifier.

Path Parameters
id

string

The unique identifier for the transaction.

e.g. b5706bac-0f58-4bf7-b8a2-987f825b74fc
Returns
200 - Successful Response
data

TransactionResource

The transaction returned in this response.

type

string

The type of this resource: transactions

id

string

The unique identifier for this transaction.

attributes

object

status

TransactionStatusEnum

The current processing status of this transaction, according to whether or not this transaction has settled or is still held.

rawText

string

(nullable)

The original, unprocessed text of the transaction. This is often not a perfect indicator of the actual merchant, but it is useful for reconciliation purposes in some cases.

description

string

A short description for this transaction. Usually the merchant name for purchases.

message

string

(nullable)

Attached message for this transaction, such as a payment message, or a transfer note.

holdInfo

HoldInfoObject

(nullable)

If this transaction is currently in the HELD status, or was ever in the HELD status, the amount and foreignAmount of the transaction while HELD.

roundUp

RoundUpObject

(nullable)

Details of how this transaction was rounded-up. If no Round Up was applied this field will be null.

cashback

CashbackObject

(nullable)

If all or part of this transaction was instantly reimbursed in the form of cashback, details of the reimbursement.

amount

MoneyObject

The amount of this transaction in Australian dollars. For transactions that were once HELD but are now SETTLED, refer to the holdInfo field for the original amount the transaction was HELD at.

foreignAmount

MoneyObject

(nullable)

The foreign currency amount of this transaction. This field will be null for domestic transactions. The amount was converted to the AUD amount reflected in the amount of this transaction. Refer to the holdInfo field for the original foreignAmount the transaction was HELD at.

settledAt

string (date-time)

(nullable)

The date-time at which this transaction settled. This field will be null for transactions that are currently in the HELD status.

createdAt

string (date-time)

The date-time at which this transaction was first encountered.

relationships

object

account

object

data

object

type

string

The type of this resource: accounts

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

category

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

parentCategory

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

tags

object

data

Array [object]

links

object

(optional)
self

string

The link to retrieve or modify linkage between this resources and the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/transactions/81a6ae62-c9ad-4388-a475-f3af80f20d8a \
-H 'Authorization: Bearer up:demo:nPxzRkSAYerEJOKu'

Sample Response

{
"data": {
"type": "transactions",
"id": "81a6ae62-c9ad-4388-a475-f3af80f20d8a",
"attributes": {
"status": "SETTLED",
"rawText": "WARUNG BEBEK, UBUD INDONES",
"description": "Warung Bebek Bengil",
"message": null,
"holdInfo": {
"amount": {
"currencyCode": "AUD",
"value": "-107.92",
"valueInBaseUnits": -10792
},
"foreignAmount": {
"currencyCode": "IDR",
"value": "-1053698.77",
"valueInBaseUnits": -105369877
}
},
"roundUp": {
"amount": {
"currencyCode": "AUD",
"value": "-0.08",
"valueInBaseUnits": -8
},
"boostPortion": null
},
"cashback": null,
"amount": {
"currencyCode": "AUD",
"value": "-107.92",
"valueInBaseUnits": -10792
},
"foreignAmount": {
"currencyCode": "IDR",
"value": "-1053698.77",
"valueInBaseUnits": -105369877
},
"settledAt": "2020-08-08T15:47:14+10:00",
"createdAt": "2020-08-10T04:00:00+10:00"
},
"relationships": {
"account": {
"data": {
"type": "accounts",
"id": "227abecc-f9b1-4ea8-8cd7-bd522fe11834"
},
"links": {
"related": "https://api.up.com.au/api/v1/accounts/227abecc-f9b1-4ea8-8cd7-bd522fe11834"
}
},
"category": {
"data": null
},
"parentCategory": {
"data": null
},
"tags": {
"data": [],
"links": {
"self": "https://api.up.com.au/api/v1/transactions/81a6ae62-c9ad-4388-a475-f3af80f20d8a/relationships/tags"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/transactions/81a6ae62-c9ad-4388-a475-f3af80f20d8a"
}
}
}
List transactions by account
GET /accounts/{accountId}/transactions

Retrieve a list of all transactions for a specific account. The returned list is paginated and can be scrolled by following the next and prev links where present. To narrow the results to a specific date range pass one or both of filter[since] and filter[until] in the query string. These filter parameters should not be used for pagination. Results are ordered newest first to oldest last.

Path Parameters
accountId

string

The unique identifier for the account.

e.g. c9db7aa8-8336-4493-9ca4-92e18278b2b4
Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30
filter[since]

string

The start date-time from which to return records, formatted according to rfc-3339. Not to be used for pagination purposes.

e.g. ?filter[since]=2020-01-01T01:02:03+10:00
filter[until]

string

The end date-time up to which to return records, formatted according to rfc-3339. Not to be used for pagination purposes.

e.g. ?filter[until]=2020-02-01T01:02:03+10:00
filter[tag]

string

A transaction tag to filter for which to return records. If the tag does not exist, zero records are returned and a success response is given.

e.g. ?filter[tag]=Holiday
Returns
200 - Successful Response
data

Array [TransactionResource]

The list of transactions returned in this response.

type

string

The type of this resource: transactions

id

string

The unique identifier for this transaction.

attributes

object

status

TransactionStatusEnum

The current processing status of this transaction, according to whether or not this transaction has settled or is still held.

rawText

string

(nullable)

The original, unprocessed text of the transaction. This is often not a perfect indicator of the actual merchant, but it is useful for reconciliation purposes in some cases.

description

string

A short description for this transaction. Usually the merchant name for purchases.

message

string

(nullable)

Attached message for this transaction, such as a payment message, or a transfer note.

holdInfo

HoldInfoObject

(nullable)

If this transaction is currently in the HELD status, or was ever in the HELD status, the amount and foreignAmount of the transaction while HELD.

roundUp

RoundUpObject

(nullable)

Details of how this transaction was rounded-up. If no Round Up was applied this field will be null.

cashback

CashbackObject

(nullable)

If all or part of this transaction was instantly reimbursed in the form of cashback, details of the reimbursement.

amount

MoneyObject

The amount of this transaction in Australian dollars. For transactions that were once HELD but are now SETTLED, refer to the holdInfo field for the original amount the transaction was HELD at.

foreignAmount

MoneyObject

(nullable)

The foreign currency amount of this transaction. This field will be null for domestic transactions. The amount was converted to the AUD amount reflected in the amount of this transaction. Refer to the holdInfo field for the original foreignAmount the transaction was HELD at.

settledAt

string (date-time)

(nullable)

The date-time at which this transaction settled. This field will be null for transactions that are currently in the HELD status.

createdAt

string (date-time)

The date-time at which this transaction was first encountered.

relationships

object

account

object

data

object

type

string

The type of this resource: accounts

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

category

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

parentCategory

object

data

object

(nullable)
type

string

The type of this resource: categories

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

tags

object

data

Array [object]

links

object

(optional)
self

string

The link to retrieve or modify linkage between this resources and the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/accounts/5306e7f6-1535-4865-a34a-dc9519623e08/transactions \
-G \
-H 'Authorization: Bearer up:demo:3gDS1RPjMaEMU4af' \
-d 'page[size]=1'

Sample Response

{
"data": [
{
"type": "transactions",
"id": "da62fbba-9db0-4c6a-a9c7-c67fc67c79e1",
"attributes": {
"status": "SETTLED",
"rawText": null,
"description": "David Taylor",
"message": "Money for the pizzas last night.",
"holdInfo": null,
"roundUp": null,
"cashback": null,
"amount": {
"currencyCode": "AUD",
"value": "-59.98",
"valueInBaseUnits": -5998
},
"foreignAmount": null,
"settledAt": "2020-08-12T10:48:18+10:00",
"createdAt": "2020-08-12T10:48:18+10:00"
},
"relationships": {
"account": {
"data": {
"type": "accounts",
"id": "5306e7f6-1535-4865-a34a-dc9519623e08"
},
"links": {
"related": "https://api.up.com.au/api/v1/accounts/5306e7f6-1535-4865-a34a-dc9519623e08"
}
},
"category": {
"data": null
},
"parentCategory": {
"data": null
},
"tags": {
"data": [
{
"type": "tags",
"id": "Pizza Night"
}
],
"links": {
"self": "https://api.up.com.au/api/v1/transactions/da62fbba-9db0-4c6a-a9c7-c67fc67c79e1/relationships/tags"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/transactions/da62fbba-9db0-4c6a-a9c7-c67fc67c79e1"
}
}
],
"links": {
"prev": null,
"next": "https://api.up.com.au/api/v1/accounts/5306e7f6-1535-4865-a34a-dc9519623e08/transactions?page%5Bafter%5D=WyIyMDIwLTA4LTEyVDAwOjQ4OjE4LjI3MDg3MDAwMFoiLCJkYTYyZmJiYS05ZGIwLTRjNmEtYTljNy1jNjdmYzY3Yzc5ZTEiXQ%3D%3D&page%5Bsize%5D=1"
}
}
Utility endpoints

Some endpoints exist not to expose data, but to test the API itself. Currently there is only one endpoint in this group: ping!

Ping
GET /util/ping

Make a basic ping request to the API. This is useful to verify that authentication is functioning correctly. On authentication success an HTTP 200 status is returned. On failure an HTTP 401 error response is returned.

Returns
200 - Successful Response
meta

object

id

string

The unique identifier of the authenticated customer.

statusEmoji

string

A cute emoji that represents the response status.

401 - Not Authorized
errors

Array [ErrorObject]

The list of errors returned in this response.

status

string

The HTTP status code associated with this error. This can also be obtained from the response headers. The status indicates the broad type of error according to HTTP semantics.

title

string

A short description of this error. This should be stable across multiple occurrences of this type of error and typically expands on the reason for the status code.

detail

string

A detailed description of this error. This should be considered unique to individual occurrences of an error and subject to change. It is useful for debugging purposes.

source

object

(optional)

If applicable, location in the request that this error relates to. This may be a parameter in the query string, or a an attribute in the request body.

parameter

string

(optional)

If this error relates to a query parameter, the name of the parameter.

pointer

string

(optional)

If this error relates to an attribute in the request body, a rfc-6901 JSON pointer to the attribute.

Sample Request

curl https://api.up.com.au/api/v1/util/ping \
-H 'Authorization: Bearer up:demo:pxVdU6tkFzHeMTx5'

Sample Response

{
"meta": {
"id": "99897b8d-1629-48c3-8077-c9a2f3454df6",
"statusEmoji": "⚡️"
}
}

Sample Request

curl https://api.up.com.au/api/v1/util/ping

Sample Response

{
"errors": [
{
"status": "401",
"title": "Not Authorized",
"detail": "The request was not authenticated because no valid credential was found in the Authorization header, or the Authorization header was not present."
}
]
}
Webhooks

Webhooks provide a mechanism for a configured URL to receive events when transaction activity occurs on Up. You can think of webhooks as being like push notifications for your server-side application.

List webhooks
GET /webhooks

Retrieve a list of configured webhooks. The returned list is paginated and can be scrolled by following the next and prev links where present. Results are ordered oldest first to newest last.

Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30
Returns
200 - Successful Response
data

Array [WebhookResource]

The list of webhooks returned in this response.

type

string

The type of this resource: webhooks

id

string

The unique identifier for this webhook.

attributes

object

url

string

The URL that this webhook is configured to POST events to.

description

string

(nullable)

An optional description that was provided at the time the webhook was created.

secretKey

string

(optional)

A shared secret key used to sign all webhook events sent to the configured webhook URL. This field is returned only once, upon the initial creation of the webhook. If lost, create a new webhook and delete this webhook.

The webhook URL receives a request with a X-Up-Authenticity-Signature header, which is the SHA-256 HMAC of the entire raw request body signed using this secretKey. It is advised to compute and check this signature to verify the authenticity of requests sent to the webhook URL. See Handling webhook events for full details.

createdAt

string (date-time)

The date-time at which this webhook was created.

relationships

object

logs

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/webhooks \
-G \
-H 'Authorization: Bearer up:demo:XyBt7KfukrEJ0a3X' \
-d 'page[size]=1'

Sample Response

{
"data": [
{
"type": "webhooks",
"id": "eaf25b5b-e132-4e0f-9f5c-65e611e67b88",
"attributes": {
"url": "http://example.com/webhook-1",
"description": "Webhook number 1",
"createdAt": "2020-08-11T17:50:19+10:00"
},
"relationships": {
"logs": {
"links": {
"related": "https://api.up.com.au/api/v1/webhooks/eaf25b5b-e132-4e0f-9f5c-65e611e67b88/logs"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/webhooks/eaf25b5b-e132-4e0f-9f5c-65e611e67b88"
}
}
],
"links": {
"prev": null,
"next": "https://api.up.com.au/api/v1/webhooks?page%5Bafter%5D=WyIyMDIwLTA4LTExVDA3OjUwOjE5LjM5MjA3MjAwMFoiLCJlYWYyNWI1Yi1lMTMyLTRlMGYtOWY1Yy02NWU2MTFlNjdiODgiXQ%3D%3D&page%5Bsize%5D=1"
}
}
Create webhook
POST /webhooks

Create a new webhook with a given URL. The URL will receive webhook events as JSON-encoded POST requests. The URL must respond with a HTTP 200 status on success.

There is currently a limit of 10 webhooks at any given time. Once this limit is reached, existing webhooks will need to be deleted before new webhooks can be created.

Event delivery is retried with exponential backoff if the URL is unreachable or it does not respond with a 200 status. The response includes a secretKey attribute, which is used to sign requests sent to the webhook URL. It will not be returned from any other endpoints within the Up API. If the secretKey is lost, simply create a new webhook with the same URL, capture its secretKey and then delete the original webhook. See Handling webhook events for details on how to process webhook events.

It is probably a good idea to test the webhook by sending it a PING event after creating it.

Request Payload
data

WebhookInputResource

The webhook resource to create.

attributes

object

url

string (uri)

The URL that this webhook should post events to. This must be a valid HTTP or HTTPS URL that does not exceed 300 characters in length.

description

string

(nullable, optional)

An optional description for this webhook, up to 64 characters in length.

Returns
201 - Created
data

WebhookResource

The webhook that was created.

type

string

The type of this resource: webhooks

id

string

The unique identifier for this webhook.

attributes

object

url

string

The URL that this webhook is configured to POST events to.

description

string

(nullable)

An optional description that was provided at the time the webhook was created.

secretKey

string

(optional)

A shared secret key used to sign all webhook events sent to the configured webhook URL. This field is returned only once, upon the initial creation of the webhook. If lost, create a new webhook and delete this webhook.

The webhook URL receives a request with a X-Up-Authenticity-Signature header, which is the SHA-256 HMAC of the entire raw request body signed using this secretKey. It is advised to compute and check this signature to verify the authenticity of requests sent to the webhook URL. See Handling webhook events for full details.

createdAt

string (date-time)

The date-time at which this webhook was created.

relationships

object

logs

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/webhooks \
-XPOST \
-H 'Authorization: Bearer up:demo:GjgAkg6R7FOSoDlW' \
-H 'Content-Type: application/json' \
--data-binary '{
"data": {
"attributes": {
"url": "http://example.com/webhook",
"description": "Example webhook"
}
}
}'

Sample Response

{
"data": {
"type": "webhooks",
"id": "38b6f028-1932-4ade-81cf-d7734220372f",
"attributes": {
"url": "http://example.com/webhook",
"description": "Example webhook",
"secretKey": "jMlNZhFDeKNa1HX2cllgAr4xdlWl8nhFy0o7UDqbEQhTww1TWhWSWee6cPWeNkSw",
"createdAt": "2020-08-13T17:50:19+10:00"
},
"relationships": {
"logs": {
"links": {
"related": "https://api.up.com.au/api/v1/webhooks/38b6f028-1932-4ade-81cf-d7734220372f/logs"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/webhooks/38b6f028-1932-4ade-81cf-d7734220372f"
}
}
}
Retrieve webhook
GET /webhooks/{id}

Retrieve a specific webhook by providing its unique identifier.

Path Parameters
id

string

The unique identifier for the webhook.

e.g. f2c683b8-b5a9-4cf0-9625-34643cf6086f
Returns
200 - Successful Response
data

WebhookResource

The webhook returned in this response.

type

string

The type of this resource: webhooks

id

string

The unique identifier for this webhook.

attributes

object

url

string

The URL that this webhook is configured to POST events to.

description

string

(nullable)

An optional description that was provided at the time the webhook was created.

secretKey

string

(optional)

A shared secret key used to sign all webhook events sent to the configured webhook URL. This field is returned only once, upon the initial creation of the webhook. If lost, create a new webhook and delete this webhook.

The webhook URL receives a request with a X-Up-Authenticity-Signature header, which is the SHA-256 HMAC of the entire raw request body signed using this secretKey. It is advised to compute and check this signature to verify the authenticity of requests sent to the webhook URL. See Handling webhook events for full details.

createdAt

string (date-time)

The date-time at which this webhook was created.

relationships

object

logs

object

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

links

object

(optional)
self

string

The canonical link to this resource within the API.

Sample Request

curl https://api.up.com.au/api/v1/webhooks/22e89894-9a15-48c3-9350-893e34c2901b \
-H 'Authorization: Bearer up:demo:IS263gsatEaUmf2i'

Sample Response

{
"data": {
"type": "webhooks",
"id": "22e89894-9a15-48c3-9350-893e34c2901b",
"attributes": {
"url": "http://example.com/webhook-2",
"description": "Webhook number 2",
"createdAt": "2020-08-12T17:50:21+10:00"
},
"relationships": {
"logs": {
"links": {
"related": "https://api.up.com.au/api/v1/webhooks/22e89894-9a15-48c3-9350-893e34c2901b/logs"
}
}
},
"links": {
"self": "https://api.up.com.au/api/v1/webhooks/22e89894-9a15-48c3-9350-893e34c2901b"
}
}
}
Delete webhook
DELETE /webhooks/{id}

Delete a specific webhook by providing its unique identifier. Once deleted, webhook events will no longer be sent to the configured URL.

Path Parameters
id

string

The unique identifier for the webhook.

e.g. 404e2251-d2a7-46f6-984a-39abfc2948e2
Returns
204 - Deleted

Sample Request

curl https://api.up.com.au/api/v1/webhooks/797c602a-b254-4f72-b4e7-5a92909ac84f \
-XDELETE \
-H 'Authorization: Bearer up:demo:SCR4dG4VSfB15mRB'
Ping webhook
POST /webhooks/{webhookId}/ping

Send a PING event to a webhook by providing its unique identifier. This is useful for testing and debugging purposes. The event is delivered asynchronously and its data is returned in the response to this request.

Path Parameters
webhookId

string

The unique identifier for the webhook.

e.g. 55689f61-e334-4ae4-9435-9b92bf077446
Returns
201 - Successful response
data

WebhookEventResource

The webhook event data sent to the subscribed webhook.

type

string

The type of this resource: webhook-events

id

string

The unique identifier for this event. This will remain constant across delivery retries.

attributes

object

eventType

WebhookEventTypeEnum

The type of this event. This can be used to determine what action to take in response to the event.

createdAt

string (date-time)

The date-time at which this event was generated.

relationships

object

webhook

object

data

object

type

string

The type of this resource: webhooks

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

transaction

object

(optional)
data

object

type

string

The type of this resource: transactions

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

Sample Request

curl https://api.up.com.au/api/v1/webhooks/a5d0c5d2-9bb4-42d5-9104-ecf3f5f0b041/ping \
-XPOST \
-H 'Authorization: Bearer up:demo:L5Io9NmBn7K7AHZg' \
-H 'Content-Type: application/json' \
--data-binary ''

Sample Response

{
"data": {
"type": "webhook-events",
"id": "3d67249c-e9df-45f7-853d-16cec10d24d5",
"attributes": {
"eventType": "PING",
"createdAt": "2020-08-13T17:50:22+10:00"
},
"relationships": {
"webhook": {
"data": {
"type": "webhooks",
"id": "a5d0c5d2-9bb4-42d5-9104-ecf3f5f0b041"
},
"links": {
"related": "https://api.up.com.au/api/v1/webhooks/a5d0c5d2-9bb4-42d5-9104-ecf3f5f0b041"
}
}
}
}
}
List webhook logs
GET /webhooks/{webhookId}/logs

Retrieve a list of delivery logs for a webhook by providing its unique identifier. This is useful for analysis and debugging purposes. The returned list is paginated and can be scrolled by following the next and prev links where present. Results are ordered newest first to oldest last. Logs may be automatically purged after a period of time.

Path Parameters
webhookId

string

The unique identifier for the webhook.

e.g. a0935b19-3abb-4390-8bda-940d62af52e0
Query Parameters
page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30
Returns
200 - Successful response
data

Array [WebhookDeliveryLogResource]

The list of delivery logs returned in this response.

type

string

The type of this resource: webhook-delivery-logs

id

string

The unique identifier for this log entry.

attributes

object

request

object

Information about the request that was sent to the webhook URL.

body

string

The payload that was sent in the request body.

response

object

(nullable)

Information about the response that was received from the webhook URL.

statusCode

integer

The HTTP status code received in the response.

body

string

The payload that was received in the response body.

deliveryStatus

WebhookDeliveryStatusEnum

The success or failure status of this delivery attempt.

createdAt

string (date-time)

The date-time at which this log entry was created.

relationships

object

webhookEvent

object

data

object

type

string

The type of this resource: webhook-events

id

string

The unique identifier of the resource within its type.

links

object

prev

string

(nullable)

The link to the previous page in the results. If this value is null there is no previous page.

next

string

(nullable)

The link to the next page in the results. If this value is null there is no next page.

Sample Request

curl https://api.up.com.au/api/v1/webhooks/d6fa188f-c8e5-45c9-b41c-8ef6953c18a8/logs \
-G \
-H 'Authorization: Bearer up:demo:QJOh1pd5HqD5qvo3' \
-d 'page[size]=1'

Sample Response

{
"data": [
{
"type": "webhook-delivery-logs",
"id": "167ef4ce-ec0b-41b3-b7d7-14959436f9aa",
"attributes": {
"request": {
"body": "{\"data\":{\"type\":\"webhook-events\",\"id\":\"c718cc98-e207-4e0e-b7a6-3d88f5eec12b\",\"attributes\":{\"eventType\":\"TRANSACTION_CREATED\",\"createdAt\":\"2020-08-12T17:51:24+10:00\"},\"relationships\":{\"webhook\":{\"data\":{\"type\":\"webhooks\",\"id\":\"d6fa188f-c8e5-45c9-b41c-8ef6953c18a8\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/webhooks/d6fa188f-c8e5-45c9-b41c-8ef6953c18a8\"}},\"transaction\":{\"data\":{\"type\":\"transactions\",\"id\":\"68694550-6bd3-46d0-a3cc-9d270135190a\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/transactions/68694550-6bd3-46d0-a3cc-9d270135190a\"}}}}}"
},
"response": {
"statusCode": 200,
"body": "{\"ok\":true}"
},
"deliveryStatus": "DELIVERED",
"createdAt": "2020-08-12T17:51:24+10:00"
},
"relationships": {
"webhookEvent": {
"data": {
"type": "webhook-events",
"id": "c718cc98-e207-4e0e-b7a6-3d88f5eec12b"
}
}
}
}
],
"links": {
"prev": null,
"next": "https://api.up.com.au/api/v1/webhooks/d6fa188f-c8e5-45c9-b41c-8ef6953c18a8/logs?page%5Bafter%5D=WyIyMDIwLTA4LTEyVDA3OjUxOjI0LjEyMjE4NTAwMFoiLCIxNjdlZjRjZS1lYzBiLTQxYjMtYjdkNy0xNDk1OTQzNmY5YWEiXQ%3D%3D&page%5Bsize%5D=1"
}
}
Handling webhook events
POST {webhookURL}// webhook

Once you have created a webhook in the Up API, events are sent to the webhook’s configured URL as JSON-encoded POST requests. The webhook URL must respond with a HTTP 200 status on success.

It is important that the URL responds in a timely manner. If the URL takes too long to respond (currently 30s), the request will be timed out. For this reason it is strongly advised to avoid any heavy processing before a response has been returned from the URL. A common solution to this problem is to use a message broker such as RabbitMQ to do the work asynchronously.

Event delivery is retried with exponential backoff in the case of any non 200 response status, if the URL is unreachable, or if the request is timed out.

Refer to the eventType attribute in order to determine what course of action to take when handling the event. The following event types are currently sent:

PING

Manually triggered by calls to the webhook ping endpoint. Used for testing and debugging purposes.

TRANSACTION_CREATED

Triggered whenever a new transaction is created in Up. This event includes a transaction relationship that provides the unique identifier for the transaction and a link to the transaction within the Up API. This link should be used to retrieve the complete transaction data.

TRANSACTION_SETTLED

Triggered whenever a transaction transitions from the HELD status to the SETTLED status. This event includes a transaction relationship that provides the unique identifier for the transaction and a link to the transaction within the Up API. This link should be used to retrieve the complete transaction data.

Due to external factors in banking processes, on rare occasions this event may not be triggered. Separate TRANSACTION_DELETED and TRANSACTION_CREATED events will be received in its place.

TRANSACTION_DELETED

Triggered whenever a HELD transaction is deleted from Up. This generally occurs for example when a hotel deposit is returned. This event includes a transaction relationship that provides the unique identifier for the transaction, however no link is provided to the transaction within the Up API as it no longer exists.

Securing Webhook Event Handlers

Incoming webhook event requests include a X-Up-Authenticity-Signature header, which can be used to verify that the event was sent by Up. Verification of the signature requires knowledge of the shared secretKey that was returned upon creation of the webhook. This key is known only to your application and to Up.

The verification process involves:

  1. Taking the raw, unparsed webhook event request body.
  2. Computing the SHA-256 HMAC signature of the request body, using the shared secretKey.
  3. Comparing the computed HMAC signature with the value of the X-Up-Authenticity-Signature header.

If the computed SHA-256 HMAC signature matches the X-Up-Authenticity-Signature header, the request is valid.

A few language-specific examples follow.

Ruby:

This example uses the Ruby on Rails framework.

require 'openssl'

def handle_webhook_event
  received_signature =
    request.headers['X-Up-Authenticity-Signature']

  signature = OpenSSL::HMAC.hexdigest(
    'SHA256',
    secret_key,
    request.raw_post,
  )

  if Rack::Utils.secure_compare(received_signature, signature)
    # Process webhook event
  end
end

PHP:

This example uses the Laravel framework.

public function handleWebhookEvent(Request $request) {
    $received_signature = $request->header(
        'X-Up-Authenticity-Signature',
    );
    $raw_body = file_get_contents('php://input');
    $signature = hash_hmac('sha256', $raw_body, $secret_key);

    if (hash_equals($signature, $received_signature)) {
        // Process webhook event
    }
}

Go:

This example is in plain Go.

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
)

func handleWebhookEvent(w http.ResponseWriter, r *http.Request) {
    received_signature, _ := hex.DecodeString(
        r.Header.Get("X-Up-Authenticity-Signature"),
    )

    mac := hmac.New(sha256.New, secret_key)
    io.Copy(mac, r.Body)
    signature := mac.Sum(nil)

    if hmac.Equal(signature, received_signature)
        // Process webhook event
    }
}

If the secretKey for a webhook is lost, simply create a new webhook with the same URL, capture the returned secretKey and delete the original webhook.

Request Headers
X-Up-Authenticity-Signature

string

The SHA-256 HMAC signature of the raw request body, signed using the secretKey of the webhook.

e.g. X-Up-Authenticity-Signature: 317c0a8ea81df3f53c1d2aef5dcbf60492d0df557197b2990e71daa4a0693364
Request Payload
data

WebhookEventResource

The webhook event data sent to the subscribed webhook.

type

string

The type of this resource: webhook-events

id

string

The unique identifier for this event. This will remain constant across delivery retries.

attributes

object

eventType

WebhookEventTypeEnum

The type of this event. This can be used to determine what action to take in response to the event.

createdAt

string (date-time)

The date-time at which this event was generated.

relationships

object

webhook

object

data

object

type

string

The type of this resource: webhooks

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

transaction

object

(optional)
data

object

type

string

The type of this resource: transactions

id

string

The unique identifier of the resource within its type.

links

object

(optional)
related

string

The link to retrieve the related resource(s) in this relationship.

Expected Response
200 - Successful Response

Sample Payload

{
"data": {
"type": "webhook-events",
"id": "6d51b963-c188-46fb-bbc2-d417cddb2b90",
"attributes": {
"eventType": "TRANSACTION_CREATED",
"createdAt": "2020-08-13T17:50:20+10:00"
},
"relationships": {
"webhook": {
"data": {
"type": "webhooks",
"id": "0b003be0-f5bf-4aec-8305-4f6cc19e41c7"
},
"links": {
"related": "https://api.up.com.au/api/v1/webhooks/0b003be0-f5bf-4aec-8305-4f6cc19e41c7"
}
},
"transaction": {
"data": {
"type": "transactions",
"id": "20ba18c8-7c1e-45fb-8079-a8f10a9b40ba"
},
"links": {
"related": "https://api.up.com.au/api/v1/transactions/20ba18c8-7c1e-45fb-8079-a8f10a9b40ba"
}
}
}
}
}