Account object, with an id prefixed acct_.
It is an identity, not a balance. Wallets, handles, deposit addresses, settlement destinations, Vaults and payments all attach to an account, and none of them exists outside one. That is why creating an account is the first call in every integration.
Create one
POST /v2/accounts is create-only and requires an Idempotency-Key. An identical retry returns the original result. The same key with a different body is refused. A new key for an externalUserId that already exists returns account_already_exists.
What comes back
A201 carrying four resources, created together: either all four exist or none does.
wallets and handle on the create call provisions the wallet, its settlement destination and the handle in the same call. Omit them and you create a bare account, then attach each resource with its own call.
Four things in that response matter later:
account.idis what you use from here. Every account-scoped path takes it. YourexternalUserIdis for lookup, throughGET /v2/accounts/external/{externalUserId}.- The handle is permanent. A handle is immutable once claimed and is never released for reuse. Whatever your customer picks is final.
ownershipVerificationStatusisunverified. The wallet is registered, but nobody has proven control of it. See Wallets and handles for what verification changes.settlementProfile.statusisactive. The first wallet that supports settlement becomes the settlement wallet. The status enum isdraft,active,inactive,failed, so readstatusrather than assuming it.
subjectType decides what the account may ever do
A
business account reaches a bank rail only through business verification (KYB). After hosted KYB is approved, a business can link its own US bank, withdraw to it, and hold a US dollar on-ramp account, where each is enabled for your app. Other countries are not available to a business. One-time payments to a third party’s bank or a local QR still require an individual account. See Business bank access.
Some rails do not serve businesses. Such a rail refuses a business account.
An account created before subjectType was required may return unclassified. It remains usable for non-regulated activity, but cannot start verification: those calls return 422 account_subject_unclassified. Contact Stableyard to classify it. You cannot create an unclassified account.
Crypto first, fiat when needed
Creating an account starts no compliance. Crypto rails depend only on your app’s product access, and work whether or not anyone has been verified. Fiat adds two gates, in this order:- Your organization completes KYB once. Until it is approved, neither you nor any of your accounts can use a fiat product. Read its standing from
compliance.partnerKybinGET /v2/partners/config. - Each account is verified when it first uses a fiat product. An
individualaccount completes KYC. Abusinessaccount that represents one of your customers completes its own KYB.
Your Business UPA
Each app environment can designate one activebusiness account as your own operating identity. The partner dashboard calls it Your Business UPA. Your organization’s KYB covers it, so it needs no separate verification. It is distinct from your customers’ accounts, including business customers.
The designation is never inferred from subjectType: "business", a handle or recent activity. Replacing it requires a Stableyard review. You can pick it as the receiver for hosted checkout, but the default checkout receiver is a separate setting and can point at another eligible account. Changing one never rewrites the other. Designating it also asks you to confirm that the account represents your own business rather than a customer; until you do, the dashboard reports it as needing that confirmation and it cannot be used as Your Business UPA.
Create a separate customer account only when a customer needs their own identity, history, destinations or compliance relationship.
What attaches to an account
What a UPA is not
- Not a balance.
GET /v2/accounts/{accountId}/balancesreturns a reporting projection, not spendable funds. It reportscustodyScope: "not_a_custody_balance", it can be negative, and it does not decrease when funds settle out to a customer’s own wallet. Do not authorise spending against it. - Not a wallet. Funds sit in the customer’s own wallet, their Vault, or their bank account.
- Not your user record. Your application owns authentication, profile and the customer relationship. The account is what money is addressed to.
Next
Capabilities
What an account can do, and what must be enabled first.
API reference
Account endpoints and full schemas.