Skip to main content
POST
Activate a regulated capability
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.

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

Idempotency-Key
string
required

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.

Required string length: 8 - 256
Pattern: ^[ -~]+$
Example:

"enable-linked-bank-user-123-v1"

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
capability
enum<string>
required

Regulated capability to make ready for this UPA.

Available options:
linked_bank,
bank_payout,
bank_onramp
country
string
required

ISO 3166-1 alpha-2 market for the requested capability.

Pattern: ^[A-Z]{2}$
Example:

"US"

currency
string
required

ISO 4217 currency for the requested capability.

Pattern: ^[A-Z]{3}$
Example:

"USD"

rail
string
required

Stableyard rail code advertised in partner configuration.

Required string length: 1 - 64
Pattern: ^[a-z0-9][a-z0-9._-]*$
Example:

"ach"

business
object

Business UPAs only. Required when creating the first hosted KYB application; omit when resuming or activating another capability.

amountAtomic
string

Optional intended amount in the requested fiat currency's atomic unit. Use only when capability eligibility depends on an amount tier.

Pattern: ^[1-9][0-9]{0,79}$
Example:

"5000"

Response

Current capability readiness and the next action, if any

accountId
string
required
Pattern: ^acct_[A-Za-z0-9_-]+$
Example:

"acct_123"

capability
object
required