Profile

Your account & payout phones

Your profile holds account-level settings — most importantly, the M-Pesa accounts used to collect KES-funded payments. Register at least one number for any Kenya-funded flow; the first you add becomes the default.

💡

The default account receives the STK push when a Kenya payment uses collectionMethod: MPESA. See the M-Pesa guide.

GET /profile

Get your profile

Returns the full profile, including your registered M-Pesa accounts in mpesaAccounts. The current default is the profile-level defaultMpesaAccountId — there is no per-account isDefault flag.

M-Pesa account object

string

UUID — reference it when updating or deleting

label

string

Friendly name

phoneNumber

string

E.164 number that receives the STK push

mobileNetwork

enum

MPESA

countryCode

enum

KE

GET /profile

{
  "id": "9f430126-99da-42e8-afb1-4cab619cda5a",
  "email": "ops@acme.com",
  "name": "Jane Doe",
  "companyName": "Acme Remittance",
  "isVerified": true,
  "defaultMpesaAccountId": "3b1e4c2a-7f10-4d6e-9a2b-2c5e8f0a1b34",
  "mpesaAccounts": [
    {
      "id": "3b1e4c2a-7f10-4d6e-9a2b-2c5e8f0a1b34",
      "label": "My Safaricom",
      "phoneNumber": "+254700000000",
      "mobileNetwork": "MPESA",
      "countryCode": "KE"
    }
  ],
  "createdAt": "2025-06-10T08:00:00.000Z",
  "updatedAt": "2025-06-10T08:00:00.000Z"
}

PATCH /profile

Update your profile

Patch editable fields — send only what you want to change. Returns the full updated profile. id, email, mpesaAccounts and defaultMpesaAccountId are read-only here (manage accounts via the endpoints below), and KYC fields lock once your account is verified.

Editable fields (all optional)

nameoptional

string

Display name

companyNameoptional

string

Business name

sectoroptional

string

Business sector

firstNameoptional

string

KYC fields (locked once verified)

phoneNumberoptional

string

Account contact number

addressoptional

object

line1, line2, city, state, postalCode, country

PATCH /profile

{
  "companyName": "Acme Pay",
  "sector": "Remittances"
}

POST /profile/mpesa

Add an M-Pesa account

Register a Safaricom number to receive STK pushes. The first account you add automatically becomes the default. Returns the full profile with a 201 status.

Body parameters

phoneNumber*

string

E.164, e.g. +254700000000

mobileNetwork*

enum

"MPESA"

countryCode*

enum

"KE"

labeloptional

string

Friendly name

⚠️

Adding a number that already exists on your profile returns 409 Conflict.

POST /profile/mpesa

{
  "phoneNumber": "+254700000000",
  "mobileNetwork": "MPESA",
  "countryCode": "KE",
  "label": "My Safaricom"
}

PATCH /profile/mpesa/:id

Update or set the default

One endpoint updates an account's fields and/or makes it the default. Send { "isDefault": true } to promote a number — the previous default is replaced. Returns the full updated profile.

⚠️

You can't unset the default with { "isDefault": false } on the current default (returns 400) — promote another account instead, so a default always exists.

PATCH /profile/mpesa/:id

{ "isDefault": true }

DELETE /profile/mpesa/:id

Remove an account

Delete a number you no longer use. Returns the full updated profile. If you remove the current default, defaultMpesaAccountId is cleared to null — set another account as default afterwards (and note that removing your only account disables M-Pesa collection).

DELETE /profile/mpesa/:id

{
  "id": "9f430126-99da-42e8-afb1-4cab619cda5a",
  "email": "ops@acme.com",
  "name": "Jane Doe",
  "companyName": "Acme Remittance",
  "isVerified": true,
  "defaultMpesaAccountId": "3b1e4c2a-7f10-4d6e-9a2b-2c5e8f0a1b34",
  "mpesaAccounts": [
    {
      "id": "3b1e4c2a-7f10-4d6e-9a2b-2c5e8f0a1b34",
      "label": "My Safaricom",
      "phoneNumber": "+254700000000",
      "mobileNetwork": "MPESA",
      "countryCode": "KE"
    }
  ],
  "createdAt": "2025-06-10T08:00:00.000Z",
  "updatedAt": "2025-06-10T08:00:00.000Z"
}