Activate a regulated capability

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "capability": "linked_bank",
  "country": "US",
  "currency": "USD",
  "rail": "ach"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations"

payload = {
    "capability": "linked_bank",
    "country": "US",
    "currency": "USD",
    "rail": "ach"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({capability: 'linked_bank', country: 'US', currency: 'USD', rail: 'ach'})
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'capability' => 'linked_bank',
    'country' => 'US',
    'currency' => 'USD',
    'rail' => 'ach'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations"

	payload := strings.NewReader("{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "payment_method_not_supported",
    "message": "The requested payment method is not supported"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

{
  "error": {
    "code": "provider_unavailable",
    "message": "The service is temporarily unavailable"
  }
}

POST

accounts

{accountId}

capability-activations

Activate a regulated capability

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "capability": "linked_bank",
  "country": "US",
  "currency": "USD",
  "rail": "ach"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations"

payload = {
    "capability": "linked_bank",
    "country": "US",
    "currency": "USD",
    "rail": "ach"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({capability: 'linked_bank', country: 'US', currency: 'USD', rail: 'ach'})
};

fetch('https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'capability' => 'linked_bank',
    'country' => 'US',
    'currency' => 'USD',
    'rail' => 'ach'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations"

	payload := strings.NewReader("{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/accounts/{accountId}/capability-activations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capability\": \"linked_bank\",\n  \"country\": \"US\",\n  \"currency\": \"USD\",\n  \"rail\": \"ach\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "payment_method_not_supported",
    "message": "The requested payment method is not supported"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

{
  "error": {
    "code": "provider_unavailable",
    "message": "The service is temporarily unavailable"
  }
}

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

Show child attributes

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

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Activate a regulated capability

Authorizations

Headers

Path Parameters

Body

Response