Create a new account (wallet) for the business

Request

Creates a wallet for the business in the requested currency. If the currency does not yet exist for the business it is provisioned first. Wallets are unique per (currency, walletType).

Security

oauth2ClientCredentials(Required scopes: accounts:write)

org_wallet_refstring

Organization wallet reference, defaults to "1" if not provided

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired

currencystringrequired

ISO 4217 currency code (uppercase, 3 letters)

Example:"USD"

walletTypestringrequired

Wallet type to create

Enum:"PETTYCASH""MAIN""SUBSCRIPTION-WALLET"

Example:"PETTYCASH"

namestringrequired

Human-readable account name shown to the user

Example:"KES Petty Cash"

descriptionstring

Optional account description (max 200 characters). Falls back to walletType when omitted.

Example:"Daily operating expenses"

ownersArray of strings

Owners list (employee ids) — optional, defaults to empty list

curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/accounts/add-new-account \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "currency": "USD",
    "walletType": "PETTYCASH",
    "name": "KES Petty Cash",
    "description": "Daily operating expenses",
    "owners": [
      "string"
    ]
  }'

Responses

Account created successfully

Bodyapplication/json

statusbooleanrequired

Whether the operation succeeded

Example:true

messagestringrequired

Human-readable status message

Example:"Account created successfully"

currencyCreatedbooleanrequired

Whether a new currency record was provisioned as part of this request

Example:false

walletobjectrequired

Created wallet payload returned by the upstream wallets service

Example:

{
  "_id": "64f1c2a5e2e2a9001f3b8e7c",
  "walletId": "123456",
  "wallet_type": "PETTYCASH",
  "currency": "USD",
  "org_wallet_ref": "2",
  "description": "Daily operating expenses"
}

Response

{
  "status": true,
  "message": "Account created successfully",
  "currencyCreated": false,
  "wallet": {
    "_id": "64f1c2a5e2e2a9001f3b8e7c",
    "walletId": "123456",
    "wallet_type": "PETTYCASH",
    "currency": "USD",
    "org_wallet_ref": "2",
    "description": "Daily operating expenses"
  }
}