Account numbers

Numbers and accounts

Every account opens with a default account number, marked is_default. It appears on the account as default_account_number and default_account_number_id. More numbers can be added, one per payer or purpose, and every one of them lands on the same balance. A business can give each payer its own number and tell incoming payments apart by the number they were sent to.

An account_number is ten digits: nine random digits, the first never zero, and a Luhn check digit. A number with one mistyped digit fails the check, so it cannot match another number the bank issued.

Creating, listing and closing

• POST /accounts/{id}/account-numbers takes a description and an Idempotency-Key. The account must be open, or the request answers accounts.account_not_open.
• GET /account-numbers lists numbers and filters by account_id or by number, which answers the question of which account a number belongs to.
• DELETE /account-numbers/{id} sets status to closed and returns the number. The default number cannot be closed on its own and answers validation_failed. Closing the account closes all of its numbers.

The routing number

Each number carries the bank's routing_number, and so does the account. The bank has no assigned ABA routing number yet. The local stack and the sandbox use the placeholder 123456780.

How incoming payments find an account

Every inbound rail looks the beneficiary's account number up and then checks the account's status. A number that was never issued is unknown, and so is a closed number on an account that is not closed. The numbers of a closed account still resolve, so the sender is told the account is closed. A book transfer that names a to_account_number uses the same lookup.

An ACH return shows on the receipt as outcome returned with its return_code and return_reason, and the bank sends the return to the originating bank in a return_file. An instant payment is answered with a rejected status report, and nothing posts. An unapplied wire has already settled to the bank, so operations either apply it to an account or return it to the sender.

Testing

The simulation endpoints deliver to an account_number through the same inbound code: an ACH entry, a wire, a FedNow or RTP credit and a check presentment. Send one to a number the bank never issued to see the outcomes in the table.