Skip to content
PayHero Africa

Update a beneficiary (alias)

PUT
/api/global/beneficiaries/{uuid}
curl --request PUT \
  --url https://api.payhero.africa/api/global/beneficiaries/a2e0434e-17ae-41b1-a1cf-1694ad63ee99 \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "John Doe", "first_name": "John", "last_name": "Doe", "surname": "example", "email": "john.doe@example.com", "country": "KE", "phone": "+254712345678", "address": "Moi Drive, Umoja", "date_of_birth": "10/03/1997", "id_number": "32460968", "id_type": "national_id", "additional_id_type": "BVN", "additional_id_number": "0123456789", "gender": "example", "marital_status": "example", "account_name": "John Doe", "account_number": "+254712345678", "account_type": "momo", "external_reference": "customer-8821", "customer_type": "retail", "is_active": false }'

Identical to PATCH /api/global/beneficiaries/{uuid} — despite the verb, PUT also merges rather than replacing. Use whichever your HTTP client prefers.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
uuid
required
string format: uuid

The beneficiary’s uuid, as returned on create.

Example
a2e0434e-17ae-41b1-a1cf-1694ad63ee99

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name

Full name, split on the first space. Required on create unless you send first_name + last_name instead, which win if both are present.

string
Example
John Doe
first_name
string
Example
John
last_name
string
Example
Doe
surname
string
email

Required for tier_0, and therefore for every beneficiary.

string format: email
Example
john.doe@example.com
country

Required for tier_0. ISO 3166-1 alpha-2 code (or country name).

string
Example
KE
phone

Required for full. Returned as phone_number.

string
Example
+254712345678
address

Required for full.

string
Example
Moi Drive, Umoja
date_of_birth

Required for full. Accepts mm/dd/yyyy (what the cross-border providers document), yyyy-mm-dd or RFC 3339. Returned as RFC 3339.

string
Example
10/03/1997
id_number

Required for full. Stored and returned as national_id. Unique per account — the same person can be a beneficiary of several merchants.

string
Example
32460968
id_type

Required for full. Must be NIN in Nigeria.

string
Example
national_id
additional_id_type

Required for full in Nigeria, where it must be BVN.

string
Example
BVN
additional_id_number

Required for full in Nigeria.

string
Example
0123456789
gender
string
marital_status
string
account_name

Destination account holder name.

string
Example
John Doe
account_number

Destination account. Backfills payment_config.account_number on payments that reference this beneficiary.

string
Example
+254712345678
account_type

Destination account type, e.g. momo or bank.

string
Example
momo
external_reference

Your own identifier for this counterparty. Unique per account, and makes POST idempotent.

string
Example
customer-8821
customer_type
string
default: retail
Allowed values: retail institution
Example
retail
is_active

Update only. Set false to stop the beneficiary transacting without deleting it.

boolean
Example
false

Responses

Section titled “Responses”

200

Section titled “200”

The updated beneficiary, with kyc_level and kyc recomputed.

Media typeapplication/json

A stored counterparty. Note that a few fields are named differently on the way out than on the way in: phone is returned as phone_number, and id_number as national_id.

object
id
integer
uuid

Send this as customer.customer_uuid on payments.

string format: uuid
first_name
string
last_name
string
surname
string | null
national_id

The id_number you sent.

string | null
date_of_birth
string | null format: date-time
gender
string | null
phone_number

The phone you sent.

string | null
email
string format: email
address
string | null
country
string
account_id

The PayHero account that owns this beneficiary, derived from your API key.

integer
account_name
string | null
account_number
string | null
account_type
string | null
customer_type
string
kyc_level

Recomputed on every write from the metadata actually present. Never settable.

string
Allowed values: tier_0 full
tier_0_lifetime_usd
number
is_active
boolean
created_at
string format: date-time
updated_at
string format: date-time
kyc

The beneficiary’s KYC standing, recomputed on every write. Read-only.

object
level
string
Allowed values: tier_0 full
full_kyc
boolean
missing_full_kyc_fields

Fields still needed to reach full. Send these to the update endpoint.

Array<string>
missing_reduced_kyc_fields

Fields still needed to reach tier_0. Non-empty only on a rejected create.

Array<string>
tier_0_lifetime_usd

Lifetime USD total this beneficiary has transacted while at tier_0.

number
tier_0_remaining_usd

Headroom left before full KYC becomes mandatory.

number
tier_0_limit_reached
boolean
tier_0_max_transaction_usd

Per-transaction ceiling while at tier_0.

number
tier_0_excluded_currencies

Currencies a tier_0 beneficiary can never transact in.

Array<string>
requires_additional_id

True when the country needs a second ID (Nigeria) and it has not been supplied.

boolean
Example
{
  "id": 94,
  "uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99",
  "first_name": "John",
  "last_name": "Doe",
  "national_id": "32460968",
  "date_of_birth": "1997-10-03T00:00:00Z",
  "phone_number": "+254712345678",
  "email": "john.doe@example.com",
  "address": "Moi Drive, Umoja",
  "country": "KE",
  "account_id": 63,
  "account_name": "John Doe",
  "account_number": "+254712345678",
  "account_type": "momo",
  "customer_type": "retail",
  "kyc_level": "tier_0",
  "tier_0_lifetime_usd": 0,
  "is_active": true,
  "kyc": {
    "level": "tier_0",
    "full_kyc": false,
    "missing_full_kyc_fields": [
      "address",
      "date_of_birth",
      "id_number",
      "id_type",
      "phone"
    ],
    "missing_reduced_kyc_fields": [],
    "tier_0_lifetime_usd": 0,
    "tier_0_remaining_usd": 200,
    "tier_0_limit_reached": false,
    "tier_0_max_transaction_usd": 20,
    "tier_0_excluded_currencies": [
      "BWP",
      "NGN",
      "ZAR"
    ],
    "requires_additional_id": false
  }
}

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
}

404

Section titled “404”

No beneficiary with that UUID exists on the account behind your API key. A UUID that belongs to another merchant also returns 404 — never 403.

Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Examples
ExampleUnknown uuid
{
  "error_code": "not_found",
  "error_message": "beneficiary \"a2e0434e-17ae-41b1-a1cf-1694ad63ee99\" does not exist",
  "status_code": 404
}