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

# Update display profile

> Set the recipient identity shown to payers. Updates use optimistic concurrency and affect only future Payments; every Payment keeps the immutable recipient display snapshot captured when it was created. App branding continues to identify the integrating platform.

Set the recipient identity shown to payers. Updates use optimistic concurrency and affect future Payments; existing Payments keep their captured recipient display snapshot.


## OpenAPI

````yaml openapi.json PUT /v2/accounts/{accountId}/display-profile
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0-staging
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: Backend API for UPAs, Payments, activity, and optional financial products.
  description: >

    Use this API from a trusted partner backend with an app ID and app secret.


    ## Recommended integration


    1. Call `GET /v2/partners/config` to verify credentials and discover enabled
    capabilities.

    2. Create a UPA only when your product needs a persistent Stableyard
    account.

    3. Create a receive or send Payment with `POST /v2/payments`.

    4. Redirect a payer to the returned `paymentUrl` or pass the Payment
    credentials to an official Stableyard interface SDK.

    5. Process signed webhooks and fetch the Payment by ID for reconciliation.


    Checkout execution and account-bound browser endpoints are intentionally
    documented in the separate Interfaces & SDKs reference. Console endpoints
    are dashboard implementation details and are not part of the partner
    integration contract.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Staging
  - url: http://localhost:3001
    description: Local
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Accounts
    x-displayName: UPA Accounts
    description: Create Universal Payment Accounts and manage account settings.
  - name: Deposit Addresses
    description: Create reusable receive addresses and verify inbound deposits.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run provider-neutral identity verification.
      Managed vaults and fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create Safe/Zodiac controlled stablecoin vaults and manage policy updates
      for accounts.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
  - name: Balances & Transactions
    description: >-
      Read Stableyard-posted financial activity. Balances are ledger projections
      of activity Stableyard processed; they are not live balances of externally
      controlled wallets.
paths:
  /v2/accounts/{accountId}/display-profile:
    put:
      tags:
        - Accounts
      summary: Update UPA display profile
      description: >-
        Set the recipient identity shown to payers. Updates use optimistic
        concurrency and affect only future Payments; every Payment keeps the
        immutable recipient display snapshot captured when it was created. App
        branding continues to identify the integrating platform.
      operationId: updateAccountDisplayProfile
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            example: acct_123
          description: Canonical account id returned by the Accounts API.
        - name: Stableyard-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2026-09-09'
          description: >-
            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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountDisplayProfileRequest'
            examples:
              example:
                summary: Update UPA display profile request
                value:
                  displayName: Acme Downtown
                  logoUrl: https://cdn.example.com/acme-downtown.png
                  expectedVersion: 0
                  reason: Update the payer-facing store identity.
      responses:
        '200':
          description: Updated account bundle
          headers:
            Stableyard-Version:
              description: >-
                Effective date-based Stableyard API contract version for this
                response.
              schema:
                type: string
                enum:
                  - '2026-09-09'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBundle'
              examples:
                example:
                  summary: Update UPA display profile 200 response
                  value:
                    account:
                      id: acct_123
                      externalUserId: user_123
                      subjectType: individual
                      status: active
                      paymentAcceptance:
                        publicReceiveEnabled: false
                        version: 1
                      metadata: {}
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '2026-08-28T10:00:00.000Z'
                    paymentHandle:
                      id: handle_123
                      accountId: acct_123
                      namespace: partner
                      handle: alice
                      status: active
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '2026-08-28T10:00:00.000Z'
                    connectedWallets:
                      - id: wallet_123
                        accountId: acct_123
                        kind: evm
                        chainId: 42161
                        address: '0x1111111111111111111111111111111111111111'
                        label: Connected wallet
                        status: active
                        ownershipVerificationStatus: unverified
                        ownershipVerificationMethod: eip712_signature
                        settlementProfileId: settle_123
                        createdAt: '2026-08-28T10:00:00.000Z'
                        updatedAt: '2026-08-28T10:00:00.000Z'
                    settlementProfile:
                      id: settle_123
                      accountId: acct_123
                      version: 2
                      connectedWalletId: wallet_123
                      settlementDestinationId: destination_123
                      status: draft
                      destinationType: smart_wallet
                      chainId: 42161
                      destinationAddress: '11111111111111111111111111111111'
                      assetSymbol: USDC
                      tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      snapshot: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - partnerBasicAuth: []
components:
  schemas:
    UpdateAccountDisplayProfileRequest:
      type: object
      additionalProperties: false
      required:
        - displayName
        - expectedVersion
        - reason
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 120
          example: Acme Downtown
        logoUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2048
          example: https://cdn.example.com/acme-downtown.png
        expectedVersion:
          type: integer
          minimum: 0
          description: Use 0 when setting the profile for the first time.
        reason:
          type: string
          minLength: 10
          maxLength: 500
          example: Update the payer-facing store identity.
    AccountBundle:
      type: object
      additionalProperties: false
      required:
        - account
        - connectedWallets
      properties:
        account:
          $ref: '#/components/schemas/Account'
        paymentHandle:
          $ref: '#/components/schemas/PaymentHandle'
        connectedWallets:
          type: array
          items:
            $ref: '#/components/schemas/ConnectedWallet'
        settlementProfile:
          $ref: '#/components/schemas/SettlementProfile'
    Account:
      type: object
      additionalProperties: false
      required:
        - id
        - externalUserId
        - subjectType
        - status
        - paymentAcceptance
        - metadata
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: acct_123
        externalUserId:
          type: string
          maxLength: 128
          example: user_123
          description: >-
            The partner-owned external user ID supplied when this account was
            created. Unicode control characters are rejected.
        subjectType:
          type: string
          enum:
            - individual
            - business
            - unclassified
          example: individual
          description: >-
            Legal subject represented by the UPA. New accounts are individual or
            business. unclassified is returned only for historical accounts
            awaiting an audited classification and cannot initiate regulated
            rails.
        status:
          type: string
          enum:
            - active
            - suspended
            - closed
        displayProfile:
          $ref: '#/components/schemas/AccountDisplayProfile'
        paymentAcceptance:
          $ref: '#/components/schemas/AccountPaymentAcceptance'
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Optional partner metadata. Must be JSON-safe, at most 4096 bytes,
            depth 3, 25 keys per object, 512 characters per string, and 50 items
            per array.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaymentHandle:
      type: object
      required:
        - id
        - accountId
        - namespace
        - handle
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: handle_123
        accountId:
          type: string
          example: acct_123
        namespace:
          type: string
          example: partner
        handle:
          type: string
          example: alice
        status:
          type: string
          enum:
            - active
            - disabled
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ConnectedWallet:
      type: object
      required:
        - id
        - accountId
        - kind
        - chainId
        - address
        - status
        - ownershipVerificationStatus
        - settlementProfileId
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: wallet_123
        accountId:
          type: string
          example: acct_123
        kind:
          type: string
          enum:
            - evm
            - tron
            - solana
            - movement
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
            - 728126428
          example: 42161
          description: >-
            Supported connected-wallet chain IDs: Arbitrum=42161, Ethereum=1,
            Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114,
            Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002,
            Tron=728126428. Address family must match the selected chain ID.
        address:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: >-
            Wallet address. EVM addresses are normalized to lowercase before
            storage; other address families retain their submitted casing.
        label:
          type:
            - string
            - 'null'
          example: Connected wallet
        status:
          type: string
          enum:
            - active
            - disabled
          description: Whether this wallet link can be used by the account.
        ownershipVerificationStatus:
          type: string
          enum:
            - unverified
            - verified
          description: >-
            Ownership is unverified until Stableyard records a successful proof.
            Linking a wallet alone never verifies ownership.
        ownershipVerificationMethod:
          type:
            - string
            - 'null'
          example: eip712_signature
        ownershipVerifiedAt:
          type:
            - string
            - 'null'
          format: date-time
        settlementProfileId:
          type:
            - string
            - 'null'
          example: settle_123
          description: >-
            The active settlement profile id when this wallet is the account
            settlement wallet; otherwise null.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SettlementProfile:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - version
        - connectedWalletId
        - settlementDestinationId
        - status
        - destinationType
        - chainId
        - destinationAddress
        - assetSymbol
        - tokenAddress
        - snapshot
      properties:
        id:
          type: string
          example: settle_123
        accountId:
          type: string
          example: acct_123
        version:
          type: integer
          minimum: 1
          example: 2
        connectedWalletId:
          type:
            - string
            - 'null'
          example: wallet_123
        settlementDestinationId:
          type:
            - string
            - 'null'
          example: destination_123
        status:
          type: string
          enum:
            - draft
            - active
            - inactive
            - failed
        destinationType:
          type: string
          enum:
            - smart_wallet
            - connected_wallet
            - external_wallet
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
          description: >-
            Supported settlement chain IDs: Arbitrum=42161, Ethereum=1,
            Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114,
            Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002.
            Settlement currently supports EVM, Solana, and Movement token
            destinations. Movement also supports THBT, while Polygon supports
            direct same-chain JPYC settlement. Tron is deposit-only for
            settlement-fee escrow.
        destinationAddress:
          type: string
          example: '11111111111111111111111111111111'
        assetSymbol:
          type: string
          enum:
            - USDC
            - USDT
            - THBT
            - JPYC
            - USDG
        tokenAddress:
          type: string
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
        snapshot:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              minLength: 1
              maxLength: 128
              example: bad_request
            message:
              type: string
              minLength: 1
              maxLength: 1000
              example: The request is invalid
            details: {}
    AccountDisplayProfile:
      type: object
      additionalProperties: false
      required:
        - displayName
        - logoUrl
        - version
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 120
          example: Acme Downtown
        logoUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2048
          example: https://cdn.example.com/acme-downtown.png
        version:
          type: integer
          minimum: 1
          example: 2
      description: >-
        Account-level recipient presentation. It identifies who is being paid
        and is distinct from app branding.
    AccountPaymentAcceptance:
      type: object
      additionalProperties: false
      required:
        - publicReceiveEnabled
        - version
      properties:
        publicReceiveEnabled:
          type: boolean
          example: false
        version:
          type: integer
          minimum: 0
          example: 1
      description: >-
        Per-UPA opt-in for public receive Payment creation. App-level public
        Payment policy is enforced separately.
  responses:
    BadRequest:
      description: Bad request
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: BadRequest response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Unauthorized:
      description: Unauthorized
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Unauthorized response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Forbidden:
      description: The app secret does not include the required scope
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Forbidden response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    NotFound:
      description: Not found
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: NotFound response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Conflict:
      description: Conflict
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Conflict response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    FailedDependency:
      description: Required chain, network, or provider configuration is missing
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: FailedDependency response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    TooManyRequests:
      description: >-
        Rate limit, payment-option limit, selection cooldown, or temporary abuse
        block
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Quota for the most constrained policy.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requests remaining in that policy window.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: Seconds until that policy window resets.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: TooManyRequests response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
  securitySchemes:
    partnerBasicAuth:
      type: http
      scheme: basic
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.