Universal Payment Accounts
Create an account
Create a Universal Payment Account (UPA) for an individual or business you serve.
POST
Pass your own stable
externalUserId and the subject’s legal classification in subjectType (individual or business). Stableyard returns the canonical account.id that every account-scoped endpoint uses. Classify the real subject the UPA represents, not the owner of a connected wallet.
You can also pass initial wallets, a handle and an email. If you send wallets and none is marked isPreferredSettlement, the first settlement-supported wallet becomes the settlement wallet. Sending email with emailVerified is equivalent to calling Verify or link an account email right after creation: emailVerified: true asserts you already verified the address and requires partner-asserted verification to be enabled for the app environment, while false starts Stableyard’s own OTP flow.
The call is create-only: an externalUserId that already has a UPA returns 409 account_already_exists. Idempotency-Key is required. Retrying with the same key and identical input returns the original account; different input returns 409 idempotency_conflict. Change wallets, settlement and the handle later through their dedicated endpoints.
See Universal Payment Account for what the account controls.Authorizations
Headers
Body
application/json
Optional UPA email, linked during account creation. Requires emailVerified.
Maximum string length:
320Example:
Set with email. true asserts you already verified this address yourself, using the same partner_asserted contract as POST /accounts/{id}/email/verification-challenges — Stableyard trusts the assertion without sending its own OTP, and only if partner-asserted verification is enabled for this app environment. false or omitted starts Stableyard's own OTP flow to that address.
Example:
true