> ## Documentation Index > Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt > Use this file to discover all available pages before exploring further. # Universal Payment Account > Create the account every resource attaches to, and read what comes back. A Universal Payment Account, or UPA, is the account record Stableyard keeps for one of your customers or merchants. In the API it is the `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 ```bash theme={null} curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts \ -u "$APP_ID:$APP_SECRET" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "externalUserId": "user_123", "subjectType": "individual", "handle": "alice", "wallets": [ { "chainId": 42161, "address": "0x1111111111111111111111111111111111111111" } ] }' ``` `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 A `201` carrying four resources, created in one transaction: ```json theme={null} { "account": { "id": "acct_123", "externalUserId": "user_123", "subjectType": "individual", "status": "active", "paymentAcceptance": { "publicReceiveEnabled": false, "version": 1 } }, "paymentHandle": { "id": "handle_123", "namespace": "partner", "handle": "alice", "status": "active" }, "connectedWallets": [ { "id": "wallet_123", "kind": "evm", "chainId": 42161, "address": "0x1111111111111111111111111111111111111111", "ownershipVerificationStatus": "unverified", "settlementProfileId": "settle_123" } ], "settlementProfile": { "id": "settle_123", "connectedWalletId": "wallet_123", "settlementDestinationId": "destination_123", "destinationType": "smart_wallet", "chainId": 42161, "assetSymbol": "USDC", "status": "draft" } } ``` Passing `wallets` and `handle` on the create call provisions the wallet, its settlement destination and the handle in the same transaction. Omit them and you create a bare account, then attach each resource with its own call. Four things in that response matter later: * **`account.id` is what you use from here.** Every account-scoped path takes it. Your `externalUserId` is for lookup, through `GET /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. * **`ownershipVerificationStatus` is `unverified`.** The wallet is registered, but nobody has proven control of it. See [Wallets and handles](/concepts/wallets-and-handles) for what verification changes. * **`settlementProfile.status` is `draft`.** The status enum is `draft`, `active`, `inactive`, `failed`. ## subjectType decides what the account may ever do ```json theme={null} "subjectType": "individual" ``` Required at creation, and **there is no endpoint that changes it**. Stableyard never infers it from the external id, the wallet, the handle, metadata or payment activity. | Value | What it can do | | - | - | | `individual` | Everything the app is entitled to, including regulated rails once identity requirements are met | | `business` | Stablecoin collection, payout, handles, deposit addresses, branded checkout and public payment pages. US bank rails once the business passes KYB | **A `business` account reaches a bank rail only through business verification (KYB).** After hosted KYB is approved under a banking program enabled for your app, a business can link its own US bank, withdraw to it, and hold a US dollar virtual account. 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](/payments/off-ramps#business-bank-access). Whether a rail serves businesses at all is decided by its provider program, not by the account. A rail whose program does not cover businesses refuses a `business` 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: 1. **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.partnerKyb` in `GET /v2/partners/config`. 2. **Each account is verified when it first uses a fiat product.** An `individual` account completes KYC. A `business` account that represents one of your customers completes its own KYB. Read an account's verification and readiness from its compliance and capability endpoints. Never infer either from a wallet, a handle, a payment or another account. ## Your Business UPA Each app environment can designate one active `business` 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 stored explicitly. It is never inferred from `subjectType: "business"`, a handle or recent activity. 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. The first assignment is audited, and replacing it goes through a Stableyard operations review. 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. Accounts predating explicit classification may return `unclassified`. They remain usable for non-regulated activity. Partners cannot create an `unclassified` account. ## What attaches to an account | Resource | What it is for | Created by | | - | - | - | | `ConnectedWallet` | A wallet the account can settle to or send from | `POST /v2/accounts/{accountId}/wallets` | | `PaymentHandle` | A human-readable address resolving to this account | `PUT /v2/accounts/{accountId}/payment-handle` | | `SettlementProfile` | Which destination collected value lands in | `PUT /v2/accounts/{accountId}/settlement-profile` | | `SettlementDestination` | A typed destination: wallet, bank account, or rail identifier | `GET /v2/accounts/{accountId}/settlement-destinations` | | `DepositAddress` | A reusable receive address, no amount, no expiry | `POST /v2/accounts/{accountId}/deposit-addresses` | | `OnrampBankAccount` | A bank account issued in the customer's name | `POST /v2/accounts/{accountId}/onramp-bank-accounts` | | `PaymentRailIdentifier` | A typed local destination, such as a UPI identifier | `POST /v2/accounts/{accountId}/payment-rail-identifiers` | | `Vault` | On-chain spending rules the owner approved | `POST /v2/accounts/{accountId}/vault` | | `Payment` | One bounded movement addressed to or from the account | `POST /v2/payments` | ## What a UPA is not * **Not a balance.** `GET /v2/accounts/{accountId}/balances` returns a reporting projection, not spendable funds. It reports `custodyScope: "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 What an account can do, and what must be enabled first. Account endpoints and full schemas. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.