Up API


const splitCode = sampleCode.split('');const formatCode = code => code;const numberOfTriangles = 1;const arbitraryNumberOfTrianglesLongArray = new Array(numberOfTriangles)  .fill(1)  .map((_, index) => formatCode(splitCode.slice(index * 2).join('')));const changeIntervalMs = 1000;const useTriangleIndex = () => {  const [triangleIndex, setTriangleIndex] = useState(0);  const updateTriangle = React.useCallback(() => {    const newIndex = (triangleIndex + 1) % numberOfTriangles;    setTriangleIndex(newIndex);  }, [triangleIndex]);  useInterval(updateTriangle, changeIntervalMs);  return triangleIndex;};type CodeBlockProps = {code: string};const codeBlockStyle = {whiteSpace: 'normal', opacity: 0.8, lineBreak: 'anywhere'};const leftTriangletyle = {  shapeOutside: 'polygon(0 0, 100% 0, 0 100%)',  height: 700,};const rightTriangleStyle = {  shapeOutside: 'polygon(0 0, 100% 0, 100% 100%)',  height: 700,};const MemoizedCodeBlock = React.memo<CodeBlockProps>(function Code({code}: CodeBlockProps) {  return (    <CodeBlock      language="jsx"      id="triangle-code-container" // used as a css selector      className="text-center"      code={code}      style={codeBlockStyle}    >      <div className="w-1/2 float-left" style={leftTriangletyle} />      <div className="w-1/2 float-right" style={rightTriangleStyle} />    </CodeBlock>  );});const Triangle = function Triangle({className, code}: Props) {  return (    <div className={classnames('overflow-hidden w-full h-full text-center', className)}>      <MemoizedCodeBlock code={code} />    </div>  );};type ContainerProps = {|  className: string,  style: Object,|};const MemoizedTriangleCode = React.memo<ContainerProps>(function TriangleCode({className, style}: ContainerProps) {  const triangleIndex = useTriangleIndex();  return (    <div style={style} className={className}>      {arbitraryNumberOfTrianglesLongArray.map((code, index) => (        <Triangle code={code} key={index} className={triangleIndex !== index ? 'hidden' : ''} />      ))}    </div>  );});export default MemoizedTriangleCode;


const formatCode = code => code;const numberOfTriangles = 1;const arbitraryNumberOfTrianglesLongArray = new Array(numberOfTriangles)  .fill(1)  .map((_, index) => formatCode(splitCode.slice(index * 2).join('')));const changeIntervalMs = 1000;const useTriangleIndex = () => {  const [triangleIndex, setTriangleIndex] = useState(0);  const updateTriangle = React.useCallback(() => {    const newIndex = (triangleIndex + 1) % numberOfTriangles;    setTriangleIndex(newIndex);  }, [triangleIndex]);  useInterval(updateTriangle, changeIntervalMs);  return triangleIndex;};type CodeBlockProps = {code: string};const codeBlockStyle = {whiteSpace: 'normal', opacity: 0.8, lineBreak: 'anywhere'};const leftTriangletyle = {  shapeOutside: 'polygon(0 0, 100% 0, 0 100%)',  height: 700,};const rightTriangleStyle = {  shapeOutside: 'polygon(0 0, 100% 0, 100% 100%)',  height: 700,};const MemoizedCodeBlock = React.memo<CodeBlockProps>(function Code({code}: CodeBlockProps) {  return (    <CodeBlock      language="jsx"      id="triangle-code-container" // used as a css selector      className="text-center"      code={code}      style={codeBlockStyle}    >      <div className="w-1/2 float-left" style={leftTriangletyle} />      <div className="w-1/2 float-right" style={rightTriangleStyle} />    </CodeBlock>  );});const Triangle = function Triangle({className, code}: Props) {  return (    <div className={classnames('overflow-hidden w-full h-full text-center', className)}>      <MemoizedCodeBlock code={code} />    </div>  );};type ContainerProps = {|  className: string,  style: Object,|};const MemoizedTriangleCode = React.memo<ContainerProps>(function TriangleCode({className, style}: ContainerProps) {  const triangleIndex = useTriangleIndex();  return (    <div style={style} className={className}>      {arbitraryNumberOfTrianglesLongArray.map((code, index) => (        <Triangle code={code} key={index} className={triangleIndex !== index ? 'hidden' : ''} />      ))}    </div>  );});export default MemoizedTriangleCode;


const numberOfTriangles = 1;const arbitraryNumberOfTrianglesLongArray = new Array(numberOfTriangles)  .fill(1)  .map((_, index) => formatCode(splitCode.slice(index * 2).join('')));const changeIntervalMs = 1000;const useTriangleIndex = () => {  const [triangleIndex, setTriangleIndex] = useState(0);  const updateTriangle = React.useCallback(() => {    const newIndex = (triangleIndex + 1) % numberOfTriangles;    setTriangleIndex(newIndex);  }, [triangleIndex]);  useInterval(updateTriangle, changeIntervalMs);  return triangleIndex;};type CodeBlockProps = {code: string};const codeBlockStyle = {whiteSpace: 'normal', opacity: 0.8, lineBreak: 'anywhere'};const leftTriangletyle = {  shapeOutside: 'polygon(0 0, 100% 0, 0 100%)',  height: 700,};const rightTriangleStyle = {  shapeOutside: 'polygon(0 0, 100% 0, 100% 100%)',  height: 700,};const MemoizedCodeBlock = React.memo<CodeBlockProps>(function Code({code}: CodeBlockProps) {  return (    <CodeBlock      language="jsx"      id="triangle-code-container" // used as a css selector      className="text-center"      code={code}      style={codeBlockStyle}    >      <div className="w-1/2 float-left" style={leftTriangletyle} />      <div className="w-1/2 float-right" style={rightTriangleStyle} />    </CodeBlock>  );});const Triangle = function Triangle({className, code}: Props) {  return (    <div className={classnames('overflow-hidden w-full h-full text-center', className)}>      <MemoizedCodeBlock code={code} />    </div>  );};type ContainerProps = {|  className: string,  style: Object,|};const MemoizedTriangleCode = React.memo<ContainerProps>(function TriangleCode({className, style}: ContainerProps) {  const triangleIndex = useTriangleIndex();  return (    <div style={style} className={className}>      {arbitraryNumberOfTrianglesLongArray.map((code, index) => (        <Triangle code={code} key={index} className={triangleIndex !== index ? 'hidden' : ''} />      ))}    </div>  );});export default MemoizedTriangleCode;


const arbitraryNumberOfTrianglesLongArray = new Array(numberOfTriangles)  .fill(1)  .map((_, index) => formatCode(splitCode.slice(index * 2).join('')));const changeIntervalMs = 1000;const useTriangleIndex = () => {  const [triangleIndex, setTriangleIndex] = useState(0);  const updateTriangle = React.useCallback(() => {    const newIndex = (triangleIndex + 1) % numberOfTriangles;    setTriangleIndex(newIndex);  }, [triangleIndex]);  useInterval(updateTriangle, changeIntervalMs);  return triangleIndex;};type CodeBlockProps = {code: string};const codeBlockStyle = {whiteSpace: 'normal', opacity: 0.8, lineBreak: 'anywhere'};const leftTriangletyle = {  shapeOutside: 'polygon(0 0, 100% 0, 0 100%)',  height: 700,};const rightTriangleStyle = {  shapeOutside: 'polygon(0 0, 100% 0, 100% 100%)',  height: 700,};const MemoizedCodeBlock = React.memo<CodeBlockProps>(function Code({code}: CodeBlockProps) {  return (    <CodeBlock      language="jsx"      id="triangle-code-container" // used as a css selector      className="text-center"      code={code}      style={codeBlockStyle}    >      <div className="w-1/2 float-left" style={leftTriangletyle} />      <div className="w-1/2 float-right" style={rightTriangleStyle} />    </CodeBlock>  );});const Triangle = function Triangle({className, code}: Props) {  return (    <div className={classnames('overflow-hidden w-full h-full text-center', className)}>      <MemoizedCodeBlock code={code} />    </div>  );};type ContainerProps = {|  className: string,  style: Object,|};const MemoizedTriangleCode = React.memo<ContainerProps>(function TriangleCode({className, style}: ContainerProps) {  const triangleIndex = useTriangleIndex();  return (    <div style={style} className={className}>      {arbitraryNumberOfTrianglesLongArray.map((code, index) => (        <Triangle code={code} key={index} className={triangleIndex !== index ? 'hidden' : ''} />      ))}    </div>  );});export default MemoizedTriangleCode;


  .map((_, index) => formatCode(splitCode.slice(index * 2).join('')));const changeIntervalMs = 1000;const useTriangleIndex = () => {  const [triangleIndex, setTriangleIndex] = useState(0);  const updateTriangle = React.useCallback(() => {    const newIndex = (triangleIndex + 1) % numberOfTriangles;    setTriangleIndex(newIndex);  }, [triangleIndex]);  useInterval(updateTriangle, changeIntervalMs);  return triangleIndex;};type CodeBlockProps = {code: string};const codeBlockStyle = {whiteSpace: 'normal', opacity: 0.8, lineBreak: 'anywhere'};const leftTriangletyle = {  shapeOutside: 'polygon(0 0, 100% 0, 0 100%)',  height: 700,};const rightTriangleStyle = {  shapeOutside: 'polygon(0 0, 100% 0, 100% 100%)',  height: 700,};const MemoizedCodeBlock = React.memo<CodeBlockProps>(function Code({code}: CodeBlockProps) {  return (    <CodeBlock      language="jsx"      id="triangle-code-container" // used as a css selector      className="text-center"      code={code}      style={codeBlockStyle}    >      <div className="w-1/2 float-left" style={leftTriangletyle} />      <div className="w-1/2 float-right" style={rightTriangleStyle} />    </CodeBlock>  );});const Triangle = function Triangle({className, code}: Props) {  return (    <div className={classnames('overflow-hidden w-full h-full text-center', className)}>      <MemoizedCodeBlock code={code} />    </div>  );};type ContainerProps = {|  className: string,  style: Object,|};const MemoizedTriangleCode = React.memo<ContainerProps>(function TriangleCode({className, style}: ContainerProps) {  const triangleIndex = useTriangleIndex();  return (    <div style={style} className={className}>      {arbitraryNumberOfTrianglesLongArray.map((code, index) => (        <Triangle code={code} key={index} className={triangleIndex !== index ? 'hidden' : ''} />      ))}    </div>  );});export default MemoizedTriangleCode;

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.

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.

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.

Pagination

Many endpoints in the Up Banking API support pagination. When an 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

For the purposes of readability these examples are not correctly URL-encoded. Care should be taken to correctly encode URL parameters when calling the API. For example "+" must be encoded as "%2B" in order to be received as a plus-sign and not as a space character.

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.

Possible values: SAVER, TRANSACTIONAL

balance

MoneyObject

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

currencyCode

string

The ISO 4217 currency code.

value

string

The amount of money, formatted as a string in the relevant currency. For example, for an Australian dollar value of $10.56, this field will be "10.56". The currency symbol is not included in the string.

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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:l1kQeuyWPj4tvdGu' \
  -d 'page[size]=1'

Sample Response

{
  "data": [
    {
      "type": "accounts",
      "id": "b20b3e0a-fc43-4525-8cd1-f701e57db03d",
      "attributes": {
        "displayName": "Up Account",
        "accountType": "TRANSACTIONAL",
        "balance": {
          "currencyCode": "AUD",
          "value": "1.00",
          "valueInBaseUnits": 100
        },
        "createdAt": "2021-02-23T13:16:23+11:00"
      },
      "relationships": {
        "transactions": {
          "links": {
            "related": "https://api.up.com.au/api/v1/accounts/b20b3e0a-fc43-4525-8cd1-f701e57db03d/transactions"
          }
        }
      },
      "links": {
        "self": "https://api.up.com.au/api/v1/accounts/b20b3e0a-fc43-4525-8cd1-f701e57db03d"
      }
    }
  ],
  "links": {
    "prev": null,
    "next": "https://api.up.com.au/api/v1/accounts?page%5Bafter%5D=WyIyMDIxLTAyLTIzVDAyOjE2OjIzLjQyNzI0NTAwMFoiLCJiMjBiM2UwYS1mYzQzLTQ1MjUtOGNkMS1mNzAxZTU3ZGIwM2QiXQ%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. 5960803c-2aa5-4d97-abdb-86a0400626c6

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.

Possible values: SAVER, TRANSACTIONAL

balance

MoneyObject

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

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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/a363aacf-666c-433f-aea9-c33444c254ae \
  -H 'Authorization: Bearer up:demo:a6IBJC68h2830ZHH'

Sample Response

{
  "data": {
    "type": "accounts",
    "id": "a363aacf-666c-433f-aea9-c33444c254ae",
    "attributes": {
      "displayName": "🐷 Savings",
      "accountType": "SAVER",
      "balance": {
        "currencyCode": "AUD",
        "value": "125.36",
        "valueInBaseUnits": 12536
      },
      "createdAt": "2021-02-23T13:16:25+11:00"
    },
    "relationships": {
      "transactions": {
        "links": {
          "related": "https://api.up.com.au/api/v1/accounts/a363aacf-666c-433f-aea9-c33444c254ae/transactions"
        }
      }
    },
    "links": {
      "self": "https://api.up.com.au/api/v1/accounts/a363aacf-666c-433f-aea9-c33444c254ae"
    }
  }
}

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:E1Qek2TzlfOwYUjv' \
  -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. e2483d07-1b3a-447d-8cd7-5bcdf95aa2ec

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/706fcec0-332c-4694-893e-0eb8d4a6fd78/relationships/tags \
  -XPOST \
  -H 'Authorization: Bearer up:demo:7wTuV2f4fQM1aStx' \
  -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. dada099c-fdec-4b29-b1f7-d015ccb686cd

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/b012facc-531c-49d3-84a9-6107c223debb/relationships/tags \
  -XDELETE \
  -H 'Authorization: Bearer up:demo:abXckj6wPsiYoOvq' \
  -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 temporarily 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[status]

The transaction status for which to return records. This can be used to filter HELD transactions from those that are SETTLED.

e.g. ?filter[status]=HELD

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[category]

string

The category identifier for which to filter transactions. Both parent and child categories can be filtered through this parameter. Providing an invalid category identifier results in a 404 response.

e.g. ?filter[category]=good-life

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.

Possible values: HELD, SETTLED

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.

amount

MoneyObject

The amount of this transaction while in the HELD status, in Australian dollars.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

foreignAmount

MoneyObject

(nullable)

The foreign currency amount of this transaction while in the HELD status. This field will be null for domestic transactions. The amount was converted to the AUD amount reflected in the amount field.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

roundUp

RoundUpObject

(nullable)

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

amount

MoneyObject

The total amount of this Round Up, including any boosts, represented as a negative value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

boostPortion

MoneyObject

(nullable)

The portion of the Round Up amount owing to boosted Round Ups, represented as a negative value. If no boost was added to the Round Up this field will be null.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

cashback

CashbackObject

(nullable)

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

description

string

A brief description of why this cashback was paid.

amount

MoneyObject

The total amount of cashback paid, represented as a positive value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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.

transferAccount

object

If this transaction is a transfer between accounts, this field will contain the account the transaction went to/came from. The amount field can be used to determine the direction of the transfer.

data

object

(nullable)

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]

type

string

The type of this resource: tags

id

string

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

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:6kypYsqBMM6SPirQ' \
  -d 'page[size]=1' \
  -d 'filter[tag]=Pizza Night' \
  -d 'filter[status]=SETTLED'

Sample Response

{
  "data": [
    {
      "type": "transactions",
      "id": "c4629293-5417-4c93-a647-081d8797c5ab",
      "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": "2021-02-22T06:14:44+11:00",
        "createdAt": "2021-02-22T06:14:44+11:00"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "65ec72f7-3c24-438d-adae-c96a6f37d005"
          },
          "links": {
            "related": "https://api.up.com.au/api/v1/accounts/65ec72f7-3c24-438d-adae-c96a6f37d005"
          }
        },
        "transferAccount": {
          "data": null
        },
        "category": {
          "data": null
        },
        "parentCategory": {
          "data": null
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "Pizza Night"
            }
          ],
          "links": {
            "self": "https://api.up.com.au/api/v1/transactions/c4629293-5417-4c93-a647-081d8797c5ab/relationships/tags"
          }
        }
      },
      "links": {
        "self": "https://api.up.com.au/api/v1/transactions/c4629293-5417-4c93-a647-081d8797c5ab"
      }
    }
  ],
  "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. 0e583d4f-63b4-497c-a0b9-d3f921817b04

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.

Possible values: HELD, SETTLED

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.

amount

MoneyObject

The amount of this transaction while in the HELD status, in Australian dollars.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

foreignAmount

MoneyObject

(nullable)

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

roundUp

RoundUpObject

(nullable)

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

amount

MoneyObject

The total amount of this Round Up, including any boosts, represented as a negative value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

boostPortion

MoneyObject

(nullable)

The portion of the Round Up amount owing to boosted Round Ups, represented as a negative value. If no boost was added to the Round Up this field will be null.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

cashback

CashbackObject

(nullable)

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

description

string

A brief description of why this cashback was paid.

amount

MoneyObject

The total amount of cashback paid, represented as a positive value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

amount

MoneyObject

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

foreignAmount

MoneyObject

(nullable)

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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.

transferAccount

object

If this transaction is a transfer between accounts, this field will contain the account the transaction went to/came from. The amount field can be used to determine the direction of the transfer.

data

object

(nullable)

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]

type

string

The type of this resource: tags

id

string

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

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/6af0d511-e5a8-4adb-9b8e-f21e69ee2e44 \
  -H 'Authorization: Bearer up:demo:sPhxnHEPERKOnXN9'

Sample Response

{
  "data": {
    "type": "transactions",
    "id": "6af0d511-e5a8-4adb-9b8e-f21e69ee2e44",
    "attributes": {
      "status": "SETTLED",
      "rawText": "WARUNG BEBEK, UBUD INDONES",
      "description": "Warung Bebek Bengil",
      "message": null,
      "holdInfo": {
        "amount": {
          "currencyCode": "AUD",
          "value": "-107.92",
          "valueInBaseUnits": -10792
        },
        "foreignAmount": null
      },
      "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": "2021-02-20T04:00:00+11:00",
      "createdAt": "2021-02-20T04:00:00+11:00"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "ca92068f-6c0e-4f63-9169-cbf0ecf97adb"
        },
        "links": {
          "related": "https://api.up.com.au/api/v1/accounts/ca92068f-6c0e-4f63-9169-cbf0ecf97adb"
        }
      },
      "transferAccount": {
        "data": null
      },
      "category": {
        "data": null
      },
      "parentCategory": {
        "data": null
      },
      "tags": {
        "data": [],
        "links": {
          "self": "https://api.up.com.au/api/v1/transactions/6af0d511-e5a8-4adb-9b8e-f21e69ee2e44/relationships/tags"
        }
      }
    },
    "links": {
      "self": "https://api.up.com.au/api/v1/transactions/6af0d511-e5a8-4adb-9b8e-f21e69ee2e44"
    }
  }
}

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. 33b2e9f7-e464-4c64-9829-7ea9e1605a2a

Query Parameters

page[size]

integer

The number of records to return in each page.

e.g. ?page[size]=30

filter[status]

The transaction status for which to return records. This can be used to filter HELD transactions from those that are SETTLED.

e.g. ?filter[status]=HELD

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[category]

string

e.g. ?filter[category]=good-life

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.

Possible values: HELD, SETTLED

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.

amount

MoneyObject

The amount of this transaction while in the HELD status, in Australian dollars.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

foreignAmount

MoneyObject

(nullable)

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

roundUp

RoundUpObject

(nullable)

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

amount

MoneyObject

The total amount of this Round Up, including any boosts, represented as a negative value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

boostPortion

MoneyObject

(nullable)

The portion of the Round Up amount owing to boosted Round Ups, represented as a negative value. If no boost was added to the Round Up this field will be null.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

cashback

CashbackObject

(nullable)

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

description

string

A brief description of why this cashback was paid.

amount

MoneyObject

The total amount of cashback paid, represented as a positive value.

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

amount

MoneyObject

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

foreignAmount

MoneyObject

(nullable)

currencyCode

string

The ISO 4217 currency code.

value

string

valueInBaseUnits

integer

The amount of money in the smallest denomination for the currency, as a 64-bit integer. For example, for an Australian dollar value of $10.56, this field will be 1056.

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.

transferAccount

object

If this transaction is a transfer between accounts, this field will contain the account the transaction went to/came from. The amount field can be used to determine the direction of the transfer.

data

object

(nullable)

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]

type

string

The type of this resource: tags

id

string

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

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/a1d0f9fb-3a2e-4c99-9363-76c024fffc9b/transactions \
  -G \
  -H 'Authorization: Bearer up:demo:BXn56KhtxgnzOOxd' \
  -d 'page[size]=1' \
  -d 'filter[status]=HELD' \
  -d 'filter[category]=good-life'

Sample Response

{
  "data": [
    {
      "type": "transactions",
      "id": "733d8cdb-97d5-4a73-be1e-6378159d934a",
      "attributes": {
        "status": "HELD",
        "rawText": "Spotify 0123456789",
        "description": "Spotify",
        "message": null,
        "holdInfo": {
          "amount": {
            "currencyCode": "AUD",
            "value": "-11.95",
            "valueInBaseUnits": -1195
          },
          "foreignAmount": null
        },
        "roundUp": null,
        "cashback": null,
        "amount": {
          "currencyCode": "AUD",
          "value": "-11.95",
          "valueInBaseUnits": -1195
        },
        "foreignAmount": null,
        "settledAt": null,
        "createdAt": "2021-02-20T09:07:58+11:00"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "a1d0f9fb-3a2e-4c99-9363-76c024fffc9b"
          },
          "links": {
            "related": "https://api.up.com.au/api/v1/accounts/a1d0f9fb-3a2e-4c99-9363-76c024fffc9b"
          }
        },
        "transferAccount": {
          "data": null
        },
        "category": {
          "data": {
            "type": "categories",
            "id": "tv-and-music"
          },
          "links": {
            "related": "https://api.up.com.au/api/v1/categories/tv-and-music"
          }
        },
        "parentCategory": {
          "data": {
            "type": "categories",
            "id": "good-life"
          },
          "links": {
            "related": "https://api.up.com.au/api/v1/categories/good-life"
          }
        },
        "tags": {
          "data": [],
          "links": {
            "self": "https://api.up.com.au/api/v1/transactions/733d8cdb-97d5-4a73-be1e-6378159d934a/relationships/tags"
          }
        }
      },
      "links": {
        "self": "https://api.up.com.au/api/v1/transactions/733d8cdb-97d5-4a73-be1e-6378159d934a"
      }
    }
  ],
  "links": {
    "prev": null,
    "next": null
  }
}

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:jrmhCCvNg4EPG0v7'

Sample Response

{
  "meta": {
    "id": "1a96cd56-5e49-4ecc-ba7e-581bff28bf7e",
    "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:c9NSNjUoNWSBrcGm' \
  -d 'page[size]=1'

Sample Response

{
  "data": [
    {
      "type": "webhooks",
      "id": "0c9389f5-a3e9-42f0-8b2c-de6e561a5f41",
      "attributes": {
        "url": "http://example.com/webhook-1",
        "description": "Webhook number 1",
        "createdAt": "2021-02-21T13:17:00+11:00"
      },
      "relationships": {
        "logs": {
          "links": {
            "related": "https://api.up.com.au/api/v1/webhooks/0c9389f5-a3e9-42f0-8b2c-de6e561a5f41/logs"
          }
        }
      },
      "links": {
        "self": "https://api.up.com.au/api/v1/webhooks/0c9389f5-a3e9-42f0-8b2c-de6e561a5f41"
      }
    }
  ],
  "links": {
    "prev": null,
    "next": "https://api.up.com.au/api/v1/webhooks?page%5Bafter%5D=WyIyMDIxLTAyLTIxVDAyOjE3OjAwLjU0NDA1NzAwMFoiLCIwYzkzODlmNS1hM2U5LTQyZjAtOGIyYy1kZTZlNTYxYTVmNDEiXQ%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)

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:QrQq3ee8D9fpormf' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "data": {
      "attributes": {
        "url": "http://example.com/webhook",
        "description": "Example webhook"
      }
    }
  }'

Sample Response

{
  "data": {
    "type": "webhooks",
    "id": "bbd5c365-8681-4916-bbb4-fd785a7ceefa",
    "attributes": {
      "url": "http://example.com/webhook",
      "description": "Example webhook",
      "secretKey": "jq4WeQvggTRTHPUKayQ7gADv9hC9cazuEdac8uaG5GZZyovg2E2u9txirR4iizcj",
      "createdAt": "2021-02-23T13:17:01+11:00"
    },
    "relationships": {
      "logs": {
        "links": {
          "related": "https://api.up.com.au/api/v1/webhooks/bbd5c365-8681-4916-bbb4-fd785a7ceefa/logs"
        }
      }
    },
    "links": {
      "self": "https://api.up.com.au/api/v1/webhooks/bbd5c365-8681-4916-bbb4-fd785a7ceefa"
    }
  }
}

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. c5f93088-fe0f-4bf9-b58c-ece4dacf0133

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)

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/afde714b-4198-48c1-af28-0d8dffac1ea4 \
  -H 'Authorization: Bearer up:demo:IZDcAYGh9dgmI7VH'

Sample Response

{
  "data": {
    "type": "webhooks",
    "id": "afde714b-4198-48c1-af28-0d8dffac1ea4",
    "attributes": {
      "url": "http://example.com/webhook-2",
      "description": "Webhook number 2",
      "createdAt": "2021-02-22T13:17:02+11:00"
    },
    "relationships": {
      "logs": {
        "links": {
          "related": "https://api.up.com.au/api/v1/webhooks/afde714b-4198-48c1-af28-0d8dffac1ea4/logs"
        }
      }
    },
    "links": {
      "self": "https://api.up.com.au/api/v1/webhooks/afde714b-4198-48c1-af28-0d8dffac1ea4"
    }
  }
}

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. e7090f89-777b-4d5e-b918-5f312930cd6b

Returns

204 - Deleted

Sample Request

curl https://api.up.com.au/api/v1/webhooks/9927a5d1-6697-4b3b-8231-f72f11a1bfc9 \
  -XDELETE \
  -H 'Authorization: Bearer up:demo:G5ZMAHnCIMHErENn'

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. f95300e7-fc15-496c-9e6a-510e3f08e8a0

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.

Possible values: TRANSACTION_CREATED, TRANSACTION_SETTLED, TRANSACTION_DELETED, PING

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/335ed20b-1df5-4f67-9a9d-593cd6c10078/ping \
  -XPOST \
  -H 'Authorization: Bearer up:demo:viUlUyR4OmOIVdTd' \
  -H 'Content-Type: application/json' \
  --data-binary ''

Sample Response

{
  "data": {
    "type": "webhook-events",
    "id": "8fff032c-df73-432f-b9a9-28ca0c0b1e65",
    "attributes": {
      "eventType": "PING",
      "createdAt": "2021-02-23T13:17:05+11:00"
    },
    "relationships": {
      "webhook": {
        "data": {
          "type": "webhooks",
          "id": "335ed20b-1df5-4f67-9a9d-593cd6c10078"
        },
        "links": {
          "related": "https://api.up.com.au/api/v1/webhooks/335ed20b-1df5-4f67-9a9d-593cd6c10078"
        }
      }
    }
  }
}

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. 18cbc33f-d374-4c74-aa26-8d210d0bc87b

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.

Possible values: DELIVERED, UNDELIVERABLE, BAD_RESPONSE_CODE

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/2be0b041-2b61-45e9-b4a5-671b1c3d80bf/logs \
  -G \
  -H 'Authorization: Bearer up:demo:nCGNvpn1rjKCpmyW' \
  -d 'page[size]=1'

Sample Response

{
  "data": [
    {
      "type": "webhook-delivery-logs",
      "id": "e81d95e5-0f8a-4f32-a99f-7d3b7f0cb75a",
      "attributes": {
        "request": {
          "body": "{\"data\":{\"type\":\"webhook-events\",\"id\":\"fd451967-591b-4b39-a0ec-cadbaf5d09cd\",\"attributes\":{\"eventType\":\"TRANSACTION_CREATED\",\"createdAt\":\"2021-02-22T13:18:07+11:00\"},\"relationships\":{\"webhook\":{\"data\":{\"type\":\"webhooks\",\"id\":\"2be0b041-2b61-45e9-b4a5-671b1c3d80bf\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/webhooks/2be0b041-2b61-45e9-b4a5-671b1c3d80bf\"}},\"transaction\":{\"data\":{\"type\":\"transactions\",\"id\":\"3e471dd2-124d-4ef1-9541-5240fceb7902\"},\"links\":{\"related\":\"https://api.up.com.au/api/v1/transactions/3e471dd2-124d-4ef1-9541-5240fceb7902\"}}}}}"
        },
        "response": {
          "statusCode": 200,
          "body": "{\"ok\":true}"
        },
        "deliveryStatus": "DELIVERED",
        "createdAt": "2021-02-22T13:18:07+11:00"
      },
      "relationships": {
        "webhookEvent": {
          "data": {
            "type": "webhook-events",
            "id": "fd451967-591b-4b39-a0ec-cadbaf5d09cd"
          }
        }
      }
    }
  ],
  "links": {
    "prev": null,
    "next": "https://api.up.com.au/api/v1/webhooks/2be0b041-2b61-45e9-b4a5-671b1c3d80bf/logs?page%5Bafter%5D=WyIyMDIxLTAyLTIyVDAyOjE4OjA3LjU1ODY1ODAwMFoiLCJlODFkOTVlNS0wZjhhLTRmMzItYTk5Zi03ZDNiN2YwY2I3NWEiXQ%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:

Taking the raw, unparsed webhook event request body.
Computing the SHA-256 HMAC signature of the request body, using the shared secretKey.
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 = $request->getContent();
    $signature = hash_hmac('sha256', $raw_body, $this->secretKey);

    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) {
    receivedSignature, _ := hex.DecodeString(
        r.Header.Get("X-Up-Authenticity-Signature"),
    )

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

    if hmac.Equal(signature, receivedSignature)
        // 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.

Possible values: TRANSACTION_CREATED, TRANSACTION_SETTLED, TRANSACTION_DELETED, PING

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": "ca651ec7-816e-4277-9c87-c58e0273329a",
    "attributes": {
      "eventType": "TRANSACTION_CREATED",
      "createdAt": "2021-02-23T13:17:01+11:00"
    },
    "relationships": {
      "webhook": {
        "data": {
          "type": "webhooks",
          "id": "6e333ed8-c0e4-4a9a-977f-fd50fdf1f6f7"
        },
        "links": {
          "related": "https://api.up.com.au/api/v1/webhooks/6e333ed8-c0e4-4a9a-977f-fd50fdf1f6f7"
        }
      },
      "transaction": {
        "data": {
          "type": "transactions",
          "id": "45fbcbb4-72ec-4528-bdf6-f8730b1afef3"
        },
        "links": {
          "related": "https://api.up.com.au/api/v1/transactions/45fbcbb4-72ec-4528-bdf6-f8730b1afef3"
        }
      }
    }
  }
}