> ## 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 checks the app entitlement, approved program market and active execution route before creating an action. * **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 a program explicitly enabled for hosted business KYB. Pass `business.legalName` on the first activation. When provisioning finishes, the response carries a credential-bearing, provider-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 ready only after provider approval. `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-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}/capability-activations: post: tags: - Identity & KYC summary: Activate a regulated capability description: >- Starts or resumes provider-neutral readiness for one regulated account capability. Individual UPAs require verified email and current identity approval. Business UPAs require a program explicitly enabled for hosted business KYB; pass business.legalName on first activation. Stableyard evaluates the app entitlement, approved program market, and active execution route 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. Business activation returns a credential-bearing provider-hosted verification link when provisioning finishes; send it only to the authorized business representative and never log or cache it. Readiness requires provider approval. 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 provider-neutral 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 the provider-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: 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 UnprocessableEntity: description: The requested payment method or refund route is not supported 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: UnprocessableEntity 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 ServiceUnavailable: description: Payment provider or escrow provisioning is unavailable 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: ServiceUnavailable 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.