Guides
How the bank's API behaves, by subject: the conventions every route shares, the objects and how they relate, and each product from the first call to the edge cases.
Guides
Getting startedRun a bank on your own machine, put demo money in it, and make the first calls. Everything here is an ordinary API call against a local sandbox, so what works here works the same way against a deployed environment.Sandbox and testingThe other side of every rail is a simulator. The simulation calls let a test play that other side: the Federal Reserve settling a file, another bank sending a wire, a merchant running a card.Open and fund an accountThis walk-through creates a customer, gets them verified in the sandbox, opens a checking account, adds an account number, funds the account three ways and reads the result. It runs against the local sandbox, which Getting started sets up. $TOKEN is a service token, as in Authentication.Move moneyMoney leaves an account four ways: a book transfer inside the bank, ACH, a wire, or an instant payment. This page compares them, shows one request for each, and says how to follow the result and handle a return.Issue a debit cardThis page starts with an open consumer checking account and ends with a cleared purchase and a declined one, all in the sandbox. Each step is one request.Make a loanThis page takes a 10,000.00 business term loan through application, closing, disbursement into checking, the first day's interest and the first payment. Each step is one request.
Working with the API
AuthenticationEvery route takes a bearer token except the few that issue one. There are two ways to get a token, for two kinds of caller.IdempotencyA request that moves money must be safe to send twice. Every write takes an Idempotency-Key, and the key decides whether a request is new.PaginationLists page by cursor, not by page number, so a page stays correct while rows are being added.ErrorsEvery error is an RFC 9457 problem document. The HTTP status says what class of thing went wrong; the code says exactly what, and never changes.Events and webhooksWhatever changes in the bank is recorded as an event. Read them from /events, or have them delivered to an endpoint of yours.
Data models
How the objects fit togetherA customer owns accounts. An account has one balance in the ledger. Money moves as transfers, and the ledger records each one as a journal. This page names the objects and says what each points to.CustomerA customer is a person or a business the bank has identified. Accounts, counterparties and groups all refer to a customer by id.AccountAn account is a deposit account: one balance in the ledger, on one product version, owned by one or more customers and reachable through one or more account numbers.TransferEach rail has its own transfer object. One summary shape covers them, so a single list shows an account's movements.Ledger, journals and holdsThe ledger is double entry. Money moves only as a journal whose debits equal its credits, and a hold reserves part of a balance without moving it.EventAn event records one change to one object. The same event can be read from /events and is what a webhook delivers.
Customers and accounts
Customers and KYCA customer is a person or a business the bank knows. Nothing opens in a customer's name until a KYC check has verified them.Opening accountsAn account is one balance in the ledger, opened on one version of a product and owned by one or more verified customers.Account numbersAn account is a balance. An account number is an address that payments use to reach it, and one account can have several.Balances and holdsAn account reports what is posted in the ledger and what can be spent. The gap between the two is made of holds, and every hold has a kind, an owner and an end.Statements and tax documentsA statement is the ledger's entries for one account and one month, issued once as an immutable PDF and delivered by email notice or on paper. The same cycle takes backup withholding, which feeds the year's 1099-INT figures.
ACH
ACH overviewThe bank originates ACH credits and debits, sends them to the ACH operator in NACHA files, and receives entries from other banks as the RDFI. The operator on the other side is a simulator today.Entry typessec_code is the entry's Standard Entry Class. The API originates three classes and refuses every other.TimingAn ACH entry settles on its effective date. This page covers how that date is chosen, the Same Day ACH windows, banking days, and when money is held and released.States and notificationsAn ACH transfer has eight states. Only its creation publishes a transfer event; the later moves are read from the file events and from the transfer itself.ReturnsA return sends an entry back with a reason code. The bank takes returns of entries it originated, and returns entries it received that cannot or should not post.Changes and prenotesA notification of change tells the originating bank that an entry posted but its details need correcting. A prenotification is a zero-dollar entry that tests an account before live entries follow.International ACH (IAT)An IAT entry is an ACH entry to or from a party outside the United States. It carries the parties, their banks and the currencies as addenda, and every name on it is screened.
Wires
Wire overviewA wire is a Fedwire funds transfer, in or out, carried as ISO 20022 messages. This page covers the messages the bank builds and reads, how to send a wire, and the other kinds of wire the API has.States and notificationsA wire moves through the states below, and its changes of state are published as events. This page lists the states as the code writes them and says which events to act on.Returns and return requestsMoney that arrived by wire goes back as a payment return (pacs.004). Money the bank sent can only be asked back, with a return request (camt.056) that the receiver may refuse. The writes on this page are operator actions: they need a staff or service identity, and a customer's token is answered forbidden.
Instant payments
Instant payments overviewFedNow and RTP payments share one resource, the Realtime Transfer. This page covers how to send one, how the answer comes back, and the limits the bank enforces.Incoming payments and returnsThe bank answers a payment another participant sends in the same exchange. This page covers that answer, returns in both directions, and the states and events of a Realtime Transfer.Request for paymentA request for payment (pain.013) asks a payer to send an instant payment. The bank's customer can send one to a payer at another institution, and can receive one and pay or decline it. Both rails carry it.
Book transfers and checks
Book transfersA book transfer moves money between two accounts at the bank. No rail is involved. It posts to the ledger at once as one journal, and it is complete when the response arrives.Issuing checksThe bank issues cashier's checks, pays the checks customers write on their accounts, and gives the account holder two controls over them: positive pay and stop payments. The check operator is a simulator today.Check depositsA deposited check is credited to the account at once, held under Regulation CC, and collected through an image cash letter. If the paying bank returns it, the amount is charged back.LockboxA lockbox is a remittance address the bank opens for a customer. Each day's mail is recorded as one remittance: every check in it is deposited to the lockbox's account, and the invoices each check pays are kept for the customer's receivables.
Cards
Cards overviewThe cards service issues debit and credit cards, decides authorizations, posts clearings and settles with each network. The card networks, the issuer-processor, the card bureau and the HSM are simulators today.Issuing and lifecycleA card is issued inactive, then activated, paused, resumed, reported or closed. This page covers the issue request, the states, the PIN and how a lost card is replaced.ControlsEvery authorization is checked against the card's own controls and against the bank's. This page lists both, and the response code each decline carries.Authorizations and clearingAn authorization is the bank's decision on one purchase. A clearing posts it, and a settlement pays the network for a day's clearings.DisputesA cardholder's dispute of a debit card purchase is a consumer error-resolution case on the deposit account. Credit card lines have a billing-error case of their own, and recoveries from a network are recorded as scheme cases.
Lending
Lending overviewThe lending service underwrites, funds and services two kinds of credit: loans that amortize on a schedule, and facilities that are drawn, billed and paid. Every product is defined as code.Applications and underwritingAn application is underwritten in the call that records it. A borderline file goes to a credit officer, and an approved loan needs a closing before money moves.Disbursement and repaymentThis page covers how an approved loan is funded into a deposit account, how interest accrues each day, how payments and payoffs are applied, and what happens when a loan falls behind.Facilities and collateralA facility is a committed line that is drawn, billed and paid. The collateral register and credit bureau furnishing come at the end.