Business verification (KYB)

A business account does not use email verification or individual KYC. It passes one business verification (KYB), hosted by a provider and started through a capability activation.

What it opens

Business verification opens US bank rails only:

Opens	Capability
Linking the company’s own US bank, and payouts to it	`linked_bank`
A USD on-ramp account	`bank_onramp`

Other countries are not available to a business. One-time payments to a third party’s bank or a local QR still require an individual account. See Universal Payment Account.

Before you start

Requirement	How to meet it
Your organization’s KYB is approved	`compliance.partnerKyb.status` in `GET /v2/partners/config`. See Onboarding overview
Stableyard has enabled business verification for your banking program	Ask Stableyard. Until then, a business activation is refused
The account was created with `subjectType: "business"`	`subjectType` cannot be changed after creation
Your app is entitled to the capability you activate	Otherwise the activation returns `403`

Start business verification

Activate any capability with business.legalName:

curl -X POST https://staging-api-v2.stableyard.fi/v2/accounts/acct_456/capability-activations \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: kyb:acct_456" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "linked_bank",
    "country": "US",
    "currency": "USD",
    "rail": "ach",
    "business": { "legalName": "Example Company Ltd" }
  }'

{
  "accountId": "acct_456",
  "capability": {
    "name": "linked_bank",
    "status": "submission_pending",
    "ready": false,
    "nextAction": { "type": "continue_business_verification" },
    "updatedAt": "2026-10-01T12:00:00Z"
  }
}

Field	Notes
`Idempotency-Key` header	Required, 8 to 256 printable characters. Keep it: you send the identical request again to get the link
`capability`	Any capability. The approval covers every capability for this business
`country`, `currency`, `rail`	A US route, such as `US`, `USD`, `ach`
`business.legalName`	3 to 100 characters. Required on the first activation

Send business.legalName on the first activation only, or when replaying that exact request. A different legal name later is refused; contact Stableyard to correct it.

Get the hosted link

The status starts at submission_pending and nextAction.type is continue_business_verification while the hosted link is prepared. Send the identical request again, with the same key. Once the link is ready:

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

The link is returned only by the activation call. GET /v2/accounts/{accountId}/capabilities never returns it.

The hosted business link in nextAction.url is a credential. Send it only to the company’s authorized representative, and never log it or keep it in browser storage.

If the link expires after the application exists, nextAction.type becomes contact_support: Stableyard support restarts it, not a new activation.

Next actions for a business

`nextAction.type`	Do this
`continue_business_verification`	Send the original activation again, with the same key, to get the current hosted link
`complete_compliance`	Send `url` to the authorized representative before `expiresAt`
`contact_support`	Stableyard must act. A new activation does not help
`none`	Approved. The capability is active

The capability’s status and ready follow the same states as any capability, starting at submission_pending rather than action_required. Use the service only when ready is true. See Capability activation.

Add more capabilities

After approval, activate bank_onramp or another capability without business. It uses the same approval, so the business does not verify again.

Errors

Code	HTTP	When
`bad_request`	400	The first business activation is missing `business.legalName`, or `business` was sent for an individual account or a program without business verification
`forbidden`	403	Your app is not entitled to this capability
`conflict`	409	A different business legal name from the one the application was started with
`idempotency_conflict`	409	The same `Idempotency-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	Fires when
`compliance.approved`	Business verification is approved and the capability is active. Read it before enabling the feature
`compliance.rejected`	Refused. Do not retry automatically
`compliance.requires_intervention`	Stopped for Stableyard operations review, including when the provider asks for more information

Poll the activation with the same key while you wait for the hosted link: no event announces it. Every compliance event is listed on Capability activation.

Capability activation

Statuses, next actions and errors for every capability.

Bank accounts

Link the company’s US bank once linked_bank is active.

On-ramp accounts

Issue USD bank details once bank_onramp is active.

Onboarding overview

Every gate between an account and a fiat rail.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Business verification (KYB)

What it opens

Before you start

Start business verification

Get the hosted link

Next actions for a business

Add more capabilities

Errors

Webhooks

Capability activation

Bank accounts

On-ramp accounts

Onboarding overview

​What it opens

​Before you start

​Start business verification

​Get the hosted link

​Next actions for a business

​Add more capabilities

​Errors

​Webhooks

​Related

Capability activation

Bank accounts

On-ramp accounts

Onboarding overview

What it opens

Before you start

Start business verification

Get the hosted link

Next actions for a business

Add more capabilities

Errors

Webhooks

Related