Activate a regulated capability for an account

A capability is one regulated service for one account, in one country, currency and rail. Identity verification proves who the customer is; activation gets the customer approved for the service by the banking partner behind it.

curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/capability-activations \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: activate:acct_123:bank_onramp:v1" \
  -H "Content-Type: application/json" \
  -d '{ "capability": "bank_onramp", "country": "US", "currency": "USD", "rail": "ach" }'

{
  "accountId": "acct_123",
  "capability": {
    "name": "bank_onramp",
    "status": "action_required",
    "ready": false,
    "nextAction": { "type": "complete_compliance", "url": "https://…", "expiresAt": "2026-10-01T12:15:00Z" },
    "updatedAt": "2026-10-01T12:00:00Z"
  }
}

Use the service only when ready is true.

The three capabilities

`capability`	What it is for
`bank_onramp`	Issuing an on-ramp account
`linked_bank`	Payouts to the customer’s own linked bank. A `business` account also needs it to link a US bank
`bank_payout`	Payouts to an external bank account, where your banking program covers that rail

The capabilities of one account rest on one banking relationship per banking program. Activate each one you use anyway: each records the customer’s consent to that service, and your app must be granted each one. Each activation also names a country (ISO 3166-1 alpha-2), a currency (ISO 4217) and a rail, such as ach. Send amountAtomic only when eligibility depends on an amount tier.

What activation needs first

Account	Needs
`individual`	A verified email and current identity eligibility. See Email verification and Individual KYC
`business`	Business verification enabled for your banking program. Its first activation carries `business.legalName`
Either	Your organization’s KYB approved, your app entitled to the capability, and exactly one banking program covering that country, currency, rail and account type

Activation is idempotent

Idempotency-Key is required, 8 to 256 printable characters. Replaying the identical body with the same key returns the current state of the original action. A changed body with the same key is refused with 409 idempotency_conflict. A new key starts a new action. Use one when the customer lost the hosted page: the new link replaces the old one, which stops working.

The hosted form

For an individual, complete_compliance carries a one-time link to a Stableyard-hosted page. On it the customer:

Confirms a code Stableyard emails to the account’s verified address.
Supplies only the details their identity verification did not already provide.
Reviews and consents to the service.

nextAction.url is a credential. Send it only to the account holder, open it before expiresAt, and never log it, cache it or put it in browser storage.

Statuses

`status`	`ready`	Meaning
`action_required`	`false`	The account holder has a hosted form to complete
`submission_pending`	`false`	The form is complete and the application is queued
`provider_review`	`false`	The banking partner is reviewing it
`active`	`true`	Approved. The service can be used
`restricted`	`false`	Was active, then frozen, suspended or withdrawn by the banking partner
`rejected`	`false`	Refused. Do not retry automatically
`closed`	`false`	Closed by the banking partner
`requires_intervention`	`false`	Stopped for Stableyard operations review

Next actions

`nextAction.type`	Do this
`complete_compliance`	Open `url` for the account holder before `expiresAt`
`compliance_in_progress`	The link was opened and the form is unfinished. If the customer lost the page, activate again with a new `Idempotency-Key`
`wait_for_compliance_review`	Nothing. Wait for `compliance.approved`, or read the capability again
`continue_business_verification`	Business only. Send the original activation again to get the current hosted link
`contact_support`	Stableyard operations must act. A new activation does not help
`none`	Nothing. The capability is active

Read every capability

curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/capabilities \
  -u "$APP_ID:$APP_SECRET"

{
  "accountId": "acct_123",
  "capabilities": [
    { "name": "bank_onramp", "status": "active", "ready": true, "nextAction": { "type": "none" }, "updatedAt": "2026-10-02T09:30:00Z" },
    { "name": "linked_bank", "status": "provider_review", "ready": false, "nextAction": { "type": "wait_for_compliance_review" }, "updatedAt": "2026-10-02T09:31:00Z" }
  ]
}

An empty capabilities array means nothing has been activated on this account. Read ready and nextAction; never keep an old hosted URL.

Business accounts

A business passes one hosted business verification, and every capability for it rests on that one approval.

Start it

Activate any capability with business.legalName. The status starts at submission_pending and nextAction.type is continue_business_verification while the hosted link is prepared.

Get the link

Send the identical request again, with the same key. Once the link is ready, nextAction.type is complete_compliance with a provider-hosted url and expiresAt. The list endpoint never returns it.

Send it to the representative

Only the company’s authorized representative. If the link expires after the application exists, nextAction.type becomes contact_support: Stableyard support restarts it, not a new activation.

Add more capabilities

After approval, activate bank_onramp or another capability without business. It uses the same approval.

Business verification opens US bank rails only. See Business KYB.

Errors

Code	HTTP	When
`bad_request`	400	`business` was sent for an individual account or a program without business verification, or the first business activation has no `business.legalName`
`forbidden`	403	Your app is not entitled to this capability
`conflict`	409	No verified email (`details.nextAction.type: "verify_account_email"`), no current identity approval (`details.nextAction.type: "complete_kyc"`), the account’s application needs operations review, or a different business legal name
`idempotency_conflict`	409	The same key with a different body
`payment_provider_unavailable`	503	No single banking program covers this country, currency, rail and account type (`details.reasonCode`)

Webhooks

Event	Meaning
`compliance.action_required`	The account holder must complete or resume a hosted action. Read the capability for the current link
`compliance.submitted`	Consent and evidence were accepted and the application was queued. Not approval
`compliance.approved`	The capability is active. Read it before enabling the feature
`compliance.rejected`	Refused. Do not retry automatically
`compliance.requires_intervention`	Stopped for operations review

Onboarding overview: the gates before activation.
On-ramp accounts: what bank_onramp unlocks.
Bank accounts: what linked_bank pays out to.
Choose your pattern: which capabilities each integration needs.

Next: Payments

The Payment object: intent, destinations, frozen snapshots and states.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Activate a regulated capability for an account

The three capabilities

What activation needs first

Activation is idempotent

The hosted form

Statuses

Next actions

Read every capability

Business accounts

Errors

Webhooks

Next: Payments

​The three capabilities

​What activation needs first

​Activation is idempotent

​The hosted form

​Statuses

​Next actions

​Read every capability

​Business accounts

​Errors

​Webhooks

​Related

Next: Payments

The three capabilities

What activation needs first

Activation is idempotent

The hosted form

Statuses

Next actions

Read every capability

Business accounts

Errors

Webhooks

Related