Payment handles
Set an account's payment handle
Assign a permanent payment handle to a UPA.
PUT
Set payment handle
A UPA’s payment handle is assigned once. Replaying the same handle is idempotent; assigning a different one returns
409 conflict with details.code: "payment_handle_immutable". Handles are never released for reuse.
A bare handle such as alice uses the authenticated app’s namespace. A qualified alice@namespace is accepted only when the namespace matches the authenticated app. Check a handle first with Check whether a payment handle is available.Authorizations
HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.
Headers
Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.
Available options:
2026-09-09 Path Parameters
Canonical account id returned by the Accounts API.
Example:
"acct_123"
Body
application/json
Bare handle uses the authenticated app namespace. Qualified alice@namespace is also accepted when the namespace matches the authenticated app.
Required string length:
3 - 105Example:
"alice"
Response
Payment handle