Skip to content
PayHero Africa

Create a Team (Account)

POST
/api/v2/accounts
curl --request POST \
  --url https://api.payhero.africa/api/v2/accounts \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "organization_id": 9, "name": "Vendor A", "description": "WiFi vendor onboarded via our platform", "email": "vendor-a@acme.co", "dial_code": "+254", "number": "711000111" }'

Provisions a new Team under your organization. A dedicated service wallet is created automatically. The Team’s currency is derived from the dial_code + number country. The creator defaults to the user behind the API key when user_id is omitted.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
organization_id
required

The organization the Team belongs to.

integer
name
required
string
description
string
email
string
dial_code

E.164 country dial code. Combined with number.

string
number

Local phone number. The Team’s currency is derived from this number’s country.

string
user_id

Creator. Defaults to the user behind the API key when omitted.

integer
username

Custom account UUID/slug. Auto-generated when omitted.

string
Examples
ExampleWiFi vendor
{
  "organization_id": 9,
  "name": "Vendor A",
  "description": "WiFi vendor onboarded via our platform",
  "email": "vendor-a@acme.co",
  "dial_code": "+254",
  "number": "711000111"
}

Responses

Section titled “Responses”

200

Section titled “200”

The created Team.

Media typeapplication/json
object
account

A Team — an isolated Account with its own scoped wallet, payment channels, KYC and members.

object
id
integer
organization_id
integer
name
string
description
string
currency

Derived from the account phone number’s country at creation.

string
number
string
email
string
status
string
account_type
string
kyc_tier
integer
kyc_verified
boolean
service_wallet_balance
number
logo
string
theme_color
string
notify_amount
integer
created_at
string format: date-time
updated_at
string format: date-time
Example
{
  "account": {
    "id": 63,
    "organization_id": 9,
    "name": "Vendor A",
    "description": "WiFi vendor onboarded via our platform",
    "currency": "KES",
    "number": "254711000111",
    "email": "vendor-a@acme.co",
    "status": "active",
    "account_type": "prepaid",
    "kyc_tier": 1,
    "kyc_verified": false,
    "service_wallet_balance": 0,
    "theme_color": "#0A7C4A",
    "notify_amount": 500
  }
}

400

Section titled “400”

The request was rejected (validation or business-rule failure).

Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Examples
{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}

401

Section titled “401”

Missing or invalid Basic auth credentials.

Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Example
{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}