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
    },
    "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
    },
    "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.

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

Given name of the person you are onboarding, used to label the account before verification collects a legal name. Whitespace-only values are stored as null.

Maximum string length: 255

Example:

"Ada"

last_name

string | null

Family name of the person you are onboarding. 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. 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

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

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Payouts

Payout Destinations

Balance

Virtual accounts

Media

Misc

Transfers

Persons

Platform Fees

Reference

Create an account

Authorizations

Headers

Body

Response