Universal Payment Account

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

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:

{
  "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 for what verification changes.
settlementProfile.status is draft. The status enum is draft, active, inactive, failed.

subjectType decides what the account may ever do

"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. 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:

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.
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.

Capabilities

What an account can do, and what must be enabled first.

API reference

Account endpoints and full schemas.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Universal Payment Account

Create one

What comes back

subjectType decides what the account may ever do

Crypto first, fiat when needed

Your Business UPA

What attaches to an account

What a UPA is not

Next

Capabilities

API reference

​Create one

​What comes back

​subjectType decides what the account may ever do

​Crypto first, fiat when needed

​Your Business UPA

​What attaches to an account

​What a UPA is not

​Next

Capabilities

API reference

Create one

What comes back

subjectType decides what the account may ever do

Crypto first, fiat when needed

Your Business UPA

What attaches to an account

What a UPA is not

Next