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

# Activate a regulated capability

> Start or resume readiness for a regulated capability such as a linked bank.

Pass the `capability` (`linked_bank`, `bank_payout` or `bank_onramp`) and the `country`, `currency` and `rail` it applies to. Stableyard first checks that the capability is enabled for your app in that country, currency and rail.

* **Individual UPAs** need a verified email and current identity approval. Any extra information or consent is collected on the Stableyard-hosted form.
* **Business UPAs** need hosted business verification (KYB) enabled for your app. Pass `business.legalName` on the first activation. While the verification link is being prepared, `nextAction.type` is `continue_business_verification`: resume the activation to get it. When it is ready, `nextAction.url` carries a third-party-hosted verification link. Send it only to the authorized business representative, and never log or cache it.

When more information or consent is required, send the one-time `nextAction.url` to the account holder. The capability is usable only once it reports `ready: true`; check it with [List regulated capability readiness](/api-reference/capabilities/list-capabilities). `Idempotency-Key` is required: identical input returns the original action, and changed input returns `409 idempotency_conflict`.

See [Off-ramps](/payments/off-ramps).


## OpenAPI

````yaml openapi.json POST /v2/accounts/{accountId}/capability-activations
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0
  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 documented in the
    separate Interfaces & SDKs reference.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Sandbox
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 identity verification. Managed vaults and
      fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create policy-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}/capability-activations:
    post:
      tags:
        - Identity & KYC
      summary: Activate a regulated capability
      description: >-
        Starts or resumes verification for one regulated account capability.
        Individual UPAs require verified email and current identity approval.
        Business UPAs need hosted business verification (KYB) enabled for your
        app; pass business.legalName on first activation. Stableyard checks that
        the capability is enabled for your app in that country, currency and
        rail before creating an action. If more information or consent is
        required, send the returned one-time `nextAction.url` to the account
        holder. Individuals use the Stableyard hosted form. When the business
        verification link is ready, `nextAction.url` carries a
        credential-bearing, third-party-hosted link; send it only to the
        authorized business representative and never log or cache it. The
        capability becomes ready once verification is approved. Replaying
        identical input with the same `Idempotency-Key` returns the original
        action, while changed input conflicts.
      operationId: activateAccountComplianceCapability
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            example: acct_123
          description: Canonical account id returned by the Accounts API.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 8
            maxLength: 256
            pattern: ^[ -~]+$
            example: enable-linked-bank-user-123-v1
          description: >-
            Required retry key for this capability activation. Reuse the same
            key only with the identical account, capability, country, currency,
            rail, and amount. Changed input returns `409 idempotency_conflict`.
        - 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/ActivateComplianceCapabilityRequest'
            examples:
              linkedBank:
                summary: Enable a linked USD bank account
                value:
                  capability: linked_bank
                  country: US
                  currency: USD
                  rail: ach
      responses:
        '200':
          description: Current capability readiness and the next action, if any
          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/ComplianceCapabilityActivationResponse'
              examples:
                actionRequired:
                  summary: >-
                    The account holder must complete a Stableyard-hosted
                    compliance action
                  value:
                    accountId: acct_123
                    capability:
                      name: linked_bank
                      status: action_required
                      ready: false
                      nextAction:
                        type: complete_compliance
                        url: https://identity.stableyard.fi/identity/c/ca_example
                        expiresAt: '2026-09-10T12:15:00.000Z'
                      updatedAt: '2026-09-10T12:00:00.000Z'
        '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'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - partnerBasicAuth: []
components:
  schemas:
    ActivateComplianceCapabilityRequest:
      type: object
      additionalProperties: false
      required:
        - capability
        - country
        - currency
        - rail
      properties:
        capability:
          type: string
          enum:
            - linked_bank
            - bank_payout
            - bank_onramp
          description: Regulated capability to make ready for this UPA.
        country:
          type: string
          pattern: ^[A-Z]{2}$
          example: US
          description: ISO 3166-1 alpha-2 market for the requested capability.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          example: USD
          description: ISO 4217 currency for the requested capability.
        rail:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9][a-z0-9._-]*$
          example: ach
          description: Stableyard rail code advertised in partner configuration.
        business:
          type: object
          additionalProperties: false
          required:
            - legalName
          description: >-
            Business UPAs only. Required when creating the first hosted KYB
            application; omit when resuming or activating another capability.
          properties:
            legalName:
              type: string
              minLength: 3
              maxLength: 100
        amountAtomic:
          type: string
          pattern: ^[1-9][0-9]{0,79}$
          example: '5000'
          description: >-
            Optional intended amount in the requested fiat currency's atomic
            unit. Use only when capability eligibility depends on an amount
            tier.
    ComplianceCapabilityActivationResponse:
      type: object
      additionalProperties: false
      required:
        - accountId
        - capability
      properties:
        accountId:
          type: string
          pattern: ^acct_[A-Za-z0-9_-]+$
          example: acct_123
        capability:
          $ref: '#/components/schemas/ComplianceCapability'
    ComplianceCapability:
      type: object
      additionalProperties: false
      required:
        - name
        - status
        - ready
        - nextAction
        - updatedAt
      properties:
        name:
          type: string
          enum:
            - linked_bank
            - bank_payout
            - bank_onramp
        status:
          type: string
          enum:
            - action_required
            - submission_pending
            - provider_review
            - active
            - restricted
            - rejected
            - closed
            - requires_intervention
        ready:
          type: boolean
        nextAction:
          $ref: '#/components/schemas/ComplianceCapabilityNextAction'
        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: {}
    ComplianceCapabilityNextAction:
      description: The next action for this capability.
      oneOf:
        - title: Resume hosted business verification
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: continue_business_verification
          description: >-
            POST the original capability activation to obtain the current hosted
            link. Do not treat this action as approval.
        - title: Complete hosted compliance
          type: object
          additionalProperties: false
          required:
            - type
            - url
            - expiresAt
          properties:
            type:
              type: string
              const: complete_compliance
            url:
              type: string
              format: uri
              description: >-
                Secure verification URL for the account holder. Individual flows
                use a one-time Stableyard link; business flows use a
                third-party-hosted KYB link. Do not log, cache or share this
                credential-bearing URL.
            expiresAt:
              type: string
              format: date-time
        - title: Wait for compliance review
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: wait_for_compliance_review
        - title: Compliance action already in progress
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: compliance_in_progress
        - title: Contact support
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: contact_support
        - title: No action required
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: none
  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: bad_request
              value:
                error:
                  code: bad_request
                  message: The request is invalid
    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
              value:
                error:
                  code: unauthorized
                  message: Authentication is required
    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
              value:
                error:
                  code: forbidden
                  message: The credential does not allow this operation
    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: not_found
              value:
                error:
                  code: not_found
                  message: The resource was not found
    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: idempotency_conflict
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The Idempotency-Key was already used with a different
                    request
    UnprocessableEntity:
      description: >-
        The request is valid but this account, method, or route cannot perform
        it
      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: payment_method_not_supported
              value:
                error:
                  code: payment_method_not_supported
                  message: The requested payment method is not supported
    FailedDependency:
      description: This feature is not configured for your app or environment
      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: chain_config_missing
              value:
                error:
                  code: chain_config_missing
                  message: The requested network is not configured for this environment
    TooManyRequests:
      description: Too many requests. Retry after the `Retry-After` interval.
      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: rate_limited
              value:
                error:
                  code: rate_limited
                  message: Too many requests
    ServiceUnavailable:
      description: Temporarily unavailable. Retry later.
      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: provider_unavailable
              value:
                error:
                  code: provider_unavailable
                  message: The service is temporarily unavailable
  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.