Banking by machine

The interface that the cityzen program uses is open to any program you write. It speaks JSON over HTTPS at /api/v1 on this address. Amounts are whole cents; an account number is twelve digits whose last is a check digit; overdrafts are refused.

Signing in

POST /api/v1/login with {"account", "password"}, giving your chequing account's number, answers {"token", "expiresAt", "customer": {"displayName", "loginAccount"}}. Send the token as Authorization: Bearer <token> on every other request. A session lasts 30 minutes and covers all of your accounts.

Answer	When
`200`	Signed in.
`400 bad_account_number`	The number is not twelve digits with a valid check digit.
`401 bad_credentials`	The number is not a chequing account that signs in, or the password is wrong.
`423 account_locked`	Five failed sign-ins in a row have locked the account for five hours, during which even the right password is refused. The answer carries `lockedUntil`, an ISO 8601 time. A successful sign-in resets the count.

Accounts and transfers

Request	Answer
`GET /api/v1/accounts`	Your accounts, each `{"number", "type", "label", "balanceCents", "currency"}`, chequing first. The type is `chequing` or `savings`; a program should show any other type as it is written.
`GET /api/v1/accounts/{number}/transactions`	One account's history, newest first, each `{"id", "at", "counterparty", "amountCents", "memo"}`: money in is positive, money out negative, and an opening deposit has no counterparty. Page with `?limit=` (up to 200) and `?before=<id>`.
`POST /api/v1/transfers`	`{"from", "to", "amountCents", "memo"}` from one of your accounts to any account. Send an `Idempotency-Key` header to make a retry safe: the transfer happens once, and the retry gets the original back. Refusals: `400` malformed, `403` not your account, `409` insufficient funds.

Every refusal is {"error", "message"}: a code for your program and a sentence for its user.

From a Robo-DOS terminal

Install the program with rpt install cityzen. Run on its own, cityzen opens terminal banking full screen: sign in, choose an account, read its transactions and send transfers, all from the keyboard. For scripts it takes commands instead:

$ cityzen -a 4123-4567-8905 accounts
Password:
Welcome, Gizele Ye.
  #  Account        Type        Label                           Balance
  1  412345678905   Chequing    Everyday                   1,250.50 CZD
  2  412345678913   Savings     Rainy day                    300.00 CZD
$ cityzen -a 412345678905 -p ******** statement 2

See man cityzen on the machine for every command.