Skip to main content
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

Authorization
string
header
required

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

Stableyard-Version
enum<string>

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

accountId
string
required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json
handle
string
required

Bare handle uses the authenticated app namespace. Qualified alice@namespace is also accepted when the namespace matches the authenticated app.

Required string length: 3 - 105
Example:

"alice"

Response

Payment handle

id
string
required
Example:

"handle_123"

accountId
string
required
Example:

"acct_123"

namespace
string
required
Example:

"partner"

handle
string
required
Example:

"alice"

status
enum<string>
required
Available options:
active,
disabled
createdAt
string<date-time>
required
updatedAt
string<date-time>
required