Create an account

curl --request POST \
  --url https://api.bachs.io/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact_email": "ada@adastores.example",
  "display_name": "Ada Stores",
  "first_name": "Ada",
  "last_name": "Okafor",
  "country": "NG",
  "entity_type": "company",
  "configuration": {
    "recipient": {
      "capabilities": {
        "payouts": {
          "requested": true
        },
        "transfers": {
          "requested": true
        }
      }
    }
  },
  "responsibilities": {
    "fees": {
      "collector": "bachs"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contact_email: 'ada@adastores.example',
    display_name: 'Ada Stores',
    first_name: 'Ada',
    last_name: 'Okafor',
    country: 'NG',
    entity_type: 'company',
    configuration: {
      recipient: {capabilities: {payouts: {requested: true}, transfers: {requested: true}}}
    },
    responsibilities: {fees: {collector: 'bachs'}}
  })
};

fetch('https://api.bachs.io/v1/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/accounts"

payload = {
    "contact_email": "ada@adastores.example",
    "display_name": "Ada Stores",
    "first_name": "Ada",
    "last_name": "Okafor",
    "country": "NG",
    "entity_type": "company",
    "configuration": { "recipient": { "capabilities": {
                "payouts": { "requested": True },
                "transfers": { "requested": True }
            } } },
    "responsibilities": { "fees": { "collector": "bachs" } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.bachs.io/v1/accounts"

	payload := strings.NewReader("{\n  \"contact_email\": \"ada@adastores.example\",\n  \"display_name\": \"Ada Stores\",\n  \"first_name\": \"Ada\",\n  \"last_name\": \"Okafor\",\n  \"country\": \"NG\",\n  \"entity_type\": \"company\",\n  \"configuration\": {\n    \"recipient\": {\n      \"capabilities\": {\n        \"payouts\": {\n          \"requested\": true\n        },\n        \"transfers\": {\n          \"requested\": true\n        }\n      }\n    }\n  },\n  \"responsibilities\": {\n    \"fees\": {\n      \"collector\": \"bachs\"\n    }\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "name": "Ada Stores",
  "owner_user_id": "usr_5e0b74c8a213",
  "parent_organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "country": "NG",
  "fee_handling": "account_pays_fee",
  "enabled_payment_methods": null,
  "adaptive_pricing": true,
  "balance_currencies": [
    "NGN"
  ],
  "phone_number": null,
  "company_name": null,
  "enabled_capabilities": [],
  "capabilities": {
    "payouts": {
      "status": "pending",
      "requested": true,
      "status_details": null,
      "international": false
    },
    "transfers": {
      "status": "pending",
      "requested": true,
      "status_details": null
    }
  },
  "requirements": {
    "currently_due": [
      "persons",
      "company.registered_name",
      "company.registration_number",
      "payout_destination"
    ],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": [],
    "errors": []
  },
  "is_active": true,
  "created_at": "2026-08-07T11:04:22.518Z",
  "updated_at": "2026-08-07T11:04:22.518Z",
  "responsibilities": {
    "fees": {
      "collector": "bachs"
    }
  },
  "configuration": {
    "recipient": {}
  }
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

POST

accounts

Create an account

curl --request POST \
  --url https://api.bachs.io/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact_email": "ada@adastores.example",
  "display_name": "Ada Stores",
  "first_name": "Ada",
  "last_name": "Okafor",
  "country": "NG",
  "entity_type": "company",
  "configuration": {
    "recipient": {
      "capabilities": {
        "payouts": {
          "requested": true
        },
        "transfers": {
          "requested": true
        }
      }
    }
  },
  "responsibilities": {
    "fees": {
      "collector": "bachs"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contact_email: 'ada@adastores.example',
    display_name: 'Ada Stores',
    first_name: 'Ada',
    last_name: 'Okafor',
    country: 'NG',
    entity_type: 'company',
    configuration: {
      recipient: {capabilities: {payouts: {requested: true}, transfers: {requested: true}}}
    },
    responsibilities: {fees: {collector: 'bachs'}}
  })
};

fetch('https://api.bachs.io/v1/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/accounts"

payload = {
    "contact_email": "ada@adastores.example",
    "display_name": "Ada Stores",
    "first_name": "Ada",
    "last_name": "Okafor",
    "country": "NG",
    "entity_type": "company",
    "configuration": { "recipient": { "capabilities": {
                "payouts": { "requested": True },
                "transfers": { "requested": True }
            } } },
    "responsibilities": { "fees": { "collector": "bachs" } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.bachs.io/v1/accounts"

	payload := strings.NewReader("{\n  \"contact_email\": \"ada@adastores.example\",\n  \"display_name\": \"Ada Stores\",\n  \"first_name\": \"Ada\",\n  \"last_name\": \"Okafor\",\n  \"country\": \"NG\",\n  \"entity_type\": \"company\",\n  \"configuration\": {\n    \"recipient\": {\n      \"capabilities\": {\n        \"payouts\": {\n          \"requested\": true\n        },\n        \"transfers\": {\n          \"requested\": true\n        }\n      }\n    }\n  },\n  \"responsibilities\": {\n    \"fees\": {\n      \"collector\": \"bachs\"\n    }\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "name": "Ada Stores",
  "owner_user_id": "usr_5e0b74c8a213",
  "parent_organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "country": "NG",
  "fee_handling": "account_pays_fee",
  "enabled_payment_methods": null,
  "adaptive_pricing": true,
  "balance_currencies": [
    "NGN"
  ],
  "phone_number": null,
  "company_name": null,
  "enabled_capabilities": [],
  "capabilities": {
    "payouts": {
      "status": "pending",
      "requested": true,
      "status_details": null,
      "international": false
    },
    "transfers": {
      "status": "pending",
      "requested": true,
      "status_details": null
    }
  },
  "requirements": {
    "currently_due": [
      "persons",
      "company.registered_name",
      "company.registration_number",
      "payout_destination"
    ],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": [],
    "errors": []
  },
  "is_active": true,
  "created_at": "2026-08-07T11:04:22.518Z",
  "updated_at": "2026-08-07T11:04:22.518Z",
  "responsibilities": {
    "fees": {
      "collector": "bachs"
    }
  },
  "configuration": {
    "recipient": {}
  }
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Scopes

connected_accounts:write

Headers

X-Account-Id

string

Account ID when acting on behalf of a sub-account.

Body

application/json

contact_email

string<email>

required

Email address of the person or business behind the account. Trimmed and lowercased before it is stored.

Example:

"ada@adastores.example"

display_name

string | null

Name you want the account listed under. Becomes the account's name, and is null until the account holder sets one during onboarding if you omit it.

Example:

"Ada Stores"

first_name

string | null

A given name used only to label the account. It does not add a person to the account and does not satisfy persons.name: add the representative through fields.persons on Update an account. Whitespace-only values are stored as null.

Maximum string length: 255

Example:

"Ada"

last_name

string | null

A family name used only to label the account. Like first_name, it does not add a person to the account. Whitespace-only values are stored as null.

Maximum string length: 255

Example:

"Okafor"

country

string | null

Two-letter ISO 3166-1 country code for the account. Decides which requirements the account is given, so set it when you already know it. Falls back to your own platform's country.

Example:

"NG"

entity_type

enum<string> | null

What kind of legal person the account is, which together with country decides the requirements it is given. company: a registered entity, asked for registration and ownership details. individual: a natural person, asked only for their own identity.

Available options:

company,

individual

Example:

"company"

configuration

object | null

Personas the account is being created for, keyed by name (merchant, recipient). No persona is ever applied automatically, recipient included. An account created with no configuration holds neither and cannot hold any capability; the personas and capabilities in your Connect setup are not applied to an API create. Only the setup's international payouts default is, when payouts is requested. Sending an empty object is rejected with 422 VALIDATION_ERROR; omit the field entirely for a persona-less account instead. A capability is only ever named inside the persona object it belongs to, in its capabilities, so naming one always names its persona in the same request; there is no way to name a capability without also naming a persona, and no way to infer one from a bare capability name. A capability nested under the wrong persona for it is rejected with 400 capability_configuration_mismatch. There is no field to apply a configuration after creation other than naming it again on update, so decide every persona the account will ever need up front, or add one later on POST /v1/accounts/{account_id}. An unrecognised key is rejected with 400 invalid_configuration.

Show child attributes

Example:

{
  "merchant": {
    "capabilities": { "card_collection": { "requested": true } }
  }
}

responsibilities

object

Fee arrangement for the account. Defaults to Bachs collecting its fee out of the charge.

Show child attributes

dashboard

enum<string>

default:none

Whether the person behind the account can log in to see their money. none: nobody logs in. light: they log in at connect.bachs.io, with your branding and no password. full: they log in to the Bachs dashboard at app.bachs.io with a Bachs login, and are invited by email when the account goes live. You can raise the mode later, but not lower it. See Give an account a dashboard.

Available options:

none,

light,

full

Example:

"light"

dashboard_features

object

What the person may change from their dashboard. Every switch starts off. Send only the switches you want to change; the rest keep their value. view_payments is always on and cannot be sent. These switches limit the person only, never your API key. See Give an account a dashboard.

Show child attributes

Example:

{ "payout_schedule": true }

Response

Account created, with the requirements the requested capabilities just surfaced.

string

Unique identifier for the account.

Example:

"acct_7KpQ2mNv4XbR9dLc"

name

string | null

The account's display name.

Example:

"Ada Stores"

owner_user_id

string

The user that owns the account. For an account you own this is a service user Bachs created; you never authenticate as it.

Example:

"usr_7b3e19d24c0a"

parent_organization_id

string | null

The platform this account is connected to, or null when it is a platform in its own right.

Example:

"acct_7KpQ2mNv4XbR9dLc"

country

string | null

Two-letter ISO 3166-1 country code. Decides which requirements the account is given.

Example:

"NG"

entity_type

enum<string> | null

Available options:

company,

individual

Example:

"company"

fee_handling

enum<string>

Who absorbs processing fees at checkout. account_pays_fee: deducted from the amount you receive. customer_pays_fee: added to what the customer pays.

Available options:

account_pays_fee,

customer_pays_fee

Example:

"account_pays_fee"

enabled_payment_methods

object | null

One entry per exact corridor (USD_CARD, NGN_CARD, NGN_BANK_TRANSFER, MOMO_GHS to MOMO_ZMW, CRYPTO). See payment method support. Each value has an enabled boolean; CRYPTO additionally carries a currencies map since it covers several asset/network pairs.

adaptive_pricing

boolean

When true, customers are shown prices in their local currency where one is available.

Example:

true

balance_currencies

string[]

Currencies this account is configured to hold a balance in.

Example:

["NGN", "USD"]

phone_number

string | null

Contact phone number, including country code.

Example:

"+2348012345678"

company_name

string | null

Registered company name, when the account is a company.

Example:

"Ada Stores Limited"

enabled_capabilities

string[] | null

Names of the capabilities currently active on this account. A convenience view of capabilities.

Example:

["transfers", "payouts"]

capabilities

object | null

Each capability's status, keyed by capability name. Populated on single-account reads only; null on list items.

Show child attributes

requirements

object | null

Outstanding requirements for this account. Populated on single-account reads only; null on list items.

Show child attributes

is_active

boolean

When false, the account is deactivated and cannot authenticate or move funds.

Example:

true

created_at

string

When the account was created, ISO 8601 in UTC.

Example:

"2026-08-01T09:12:44.000Z"

updated_at

string

When the account was last updated, ISO 8601 in UTC.

Example:

"2026-08-07T11:04:22.518Z"

responsibilities

object | null

Fee arrangement for an account you own. null when this object is not an account you own.

Show child attributes

configuration

object | null

Personas applied to this account, keyed by name (merchant, recipient), each with an empty object as its value. Populated on single-account reads, where it is {} when none apply; null on list items.

Show child attributes

Example:

{ "merchant": {}, "recipient": {} }

dashboard

enum<string>

The account's access mode. See Give an account a dashboard.

Available options:

none,

light,

full

Example:

"light"

dashboard_features

object

All five switches. view_payments is true in light and full mode. In none mode every switch reads false, because nobody logs in; the switches you set come back if you raise the mode.

Show child attributes

Example:

{
  "view_payments": true,
  "payout_schedule": true,
  "manual_payouts": false,
  "change_payout_destination": false,
  "refunds": false
}

dashboard_access

enum<string>

not_invited: nobody has logged in yet. invited: a full invite is out, and nobody has accepted it yet. active: the person behind the account has logged in at least once, or accepted the full invite.

Available options:

not_invited,

invited,

active

Example:

"not_invited"

liveness_owed

boolean | null

true when the person behind the account still needs to do the selfie video check. Send them a liveness account link. Only on a single-account read. See The selfie video check.

Example:

false

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Files

Media

Misc

Transfers

Persons

Platform Fees

Reference

Create an account

Authorizations

Scopes

Headers

Body

Response