Accounts and payto addresses
Every account is a set of payto:// addresses, stored encrypted and only ever returned masked.
An account (acct_…) is somewhere money can come from or go to. There are two ways to get one:
- Linked through a link session. The account carries
link(thelnk_…it came from), and Unirail can initiate payments from it through the provider that linked it. - Registered from details a payee gave you, with
POST /v1/accounts. Nothing is linked; the account can receive.
const payee = await unirail.accounts.create({
customer: contact.unirailCustomerId, // optional
holderName: "Ada Lovelace",
payto: "payto://scan/040004/12345678?receiver-name=Ada%20Lovelace",
});payto:// addresses
Account identifiers are payto:// URIs, extended with the schemes Unirail models:
| Scheme | Example |
|---|---|
scan | payto://scan/040004/12345678 (UK sort code and account number) |
iban | payto://iban/DE75512108001245126199 |
bban | payto://bban/NO/86011117947 |
ach | payto://ach/021000021/1234567890?type=checking |
bsb | payto://bsb/062000/12345678 |
sgacct | payto://sgacct/7171/1234567890 |
caip10 | payto://caip10/eip155:1:0xab16… |
Routing in this version covers scan and iban. Other schemes parse and store, and routes to them come back infeasible with a reason until a provider binding covers them. The optional receiver-name parameter carries the holder's name and is not part of the identifier.
To check an address without storing it, call POST /v1/addresses/parse:
const parsed = await unirail.addresses.parse({ payto: "payto://iban/DE75512108001245126199" });
// { scheme: "iban", known: true, masked: "DE75 •••• 6199", … }Masking
Account identifiers are secrets. Unirail stores them with envelope encryption and never returns them in full. Each entry in account.addresses gives you:
| Field | Meaning |
|---|---|
scheme | The payto scheme, such as scan or iban. |
masked | A display form such as •••• 5678. |
fingerprint | A keyed hash. Equal fingerprints mean the same account details, so you can spot duplicates without seeing them. |
verification | status (unverified, verified, mismatch, failed), source (own-link, cop, aisp-ownership, micro-deposit, proxy-lookup, entered) and verifiedAt. |
Once your accounts live in Unirail you can stop storing sort codes and account numbers yourself.
Status and capabilities
An account is active, reauth-required (the user's consent with the provider lapsed; you'll get account.reauth_required) or revoked. capabilities lists, per rail and direction (send or receive), whether the account can be used and why not when it can't.