Transactions

Transactions involve shifting amounts from one account to another.

Attribute	Description
amount	The amount to transfer from the sender account.
reference	A reference for the transaction.

Relationship	Description
sender	The account to send this transaction from.
recipient	The account to send this transaction to.

Meta	Description
exchangeRate	The exchange rate of the transaction, if applicable.
createdAt	The timestamp (UTC) (ISO8601) when the transaction was created.

• meta.exchangeRate will be omitted if the two accounts are the same currency.

---

List transactions

get

Authorizations

AuthToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

filter[account]stringOptional

Filter all transactions where either the sender or recipient is a specific account ID.

Example: a1b2c3d4e5

filter[sender]stringOptional

Filter all transactions where the sender is a specific account ID.

Example: a1b2c3d4e5

filter[recipient]stringOptional

Filter all transactions where the recipient is a specific account ID.

Example: a1b2c3d4e5

filter[reference]stringOptional

Filter all transactions where the reference contains a specific substring.

Example: hello-world

page[page]integerOptional

Set the page number of resources to return.

Default: 1

page[limit]integer · max: 100Optional

Set the maximum number of resources to return.

Default: 20

Responses

200

List of Transactions

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

500

An error occurred

application/json

get

/transactions

HTTPcURLJavaScriptPython

GET /transactions HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "type": "transactions",
      "id": "c3d4e5f6g7",
      "attributes": {
        "amount": "100.00",
        "reference": "text"
      },
      "relationships": {
        "sender": {
          "data": {
            "type": "accounts",
            "id": "a1b2c3d4e5"
          }
        },
        "recipient": {
          "data": {
            "type": "accounts",
            "id": "a1b2c3d4e5"
          }
        }
      },
      "meta": {
        "exchangeRate": 1,
        "createdAt": "2023-07-12T19:00:00.000Z"
      }
    }
  ],
  "meta": {
    "prev": "/resource?page[count]=2&page[limit]=100",
    "next": "/resource?page[count]=4&page[limit]=100",
    "first": "/resource?page[count]=1&page[limit]=100",
    "last": "/resource?page[count]=10&page[limit]=100"
  }
}

---

Create transaction

post

Authorizations

AuthToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

Responses

200

Created transaction

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

post

/transactions

HTTPcURLJavaScriptPython

POST /transactions HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    }
  }
}

{
  "data": {
    "type": "transactions",
    "id": "c3d4e5f6g7",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    },
    "meta": {
      "exchangeRate": 1,
      "createdAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

• You cannot edit or delete a transaction after created.

---

Get transaction by ID

get

Authorizations

AuthToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

transactionIdstringRequired

Transaction ID

Example: c3d4e5f6h7

Responses

200

Found transaction

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

get

/transactions/{transactionId}

HTTPcURLJavaScriptPython

GET /transactions/{transactionId} HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "type": "transactions",
    "id": "c3d4e5f6g7",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    },
    "meta": {
      "exchangeRate": 1,
      "createdAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

---

Examples

Crediting your account

• You can credit your account by specifying "ROOT" as the sender account ID, and one of your accounts as the recipient.

• This is a Create event, similar to minting new coin, where you receive "funds" from nothing.

• Yes, you can credit your account insane amounts (but it's not real!).

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Opening account"
    },
    "relationships": {
      // Specify ROOT as the sender
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      // Specify one of your accounts as the recipient
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Opening account"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

Emptying your account

• You can empty your account by specifying "ROOT" as the recipient account ID.

• This is a Destroy event, where you send "funds" into nothing.

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Closing account"
    },
    "relationships": {
      // Specify one of your accounts as the sender
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      // Specify ROOT as the recipient
      "recipient": { "data": { "type": "accounts", "id": "ROOT" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Closing account"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

Transfer between 2 accounts

You can transfer funds between 2 accounts by specifying the relevant recipient account ID.

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Lunch money"
    },
    "relationships": {
      // Specify one of your accounts as the sender
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      // Specify another of your accounts as the sender
      "recipient": { "data": { "type": "accounts", "id": "f6g7h8i9j0" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Lunch money"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

• You can transfer from any of your accounts.

• You can transfer to any of your accounts, or any public/unlisted account.

As of now, you cannot transfer between accounts of different currencies.

Currency conversion will be addressed in a future version of this API.