Fetch a beneficiary

GET

/api/global/beneficiaries/{uuid}

cURL

curl "https://api.payhero.africa/api/global/beneficiaries/a2e0434e-17ae-41b1-a1cf-1694ad63ee99" \
  -u "API_USERNAME:API_PASSWORD"

Returns a single beneficiary. A UUID that belongs to another merchant returns 404, never 403.

Authorizations

basicAuth

Parameters

Path Parameters

uuid

required

string format: uuid

The beneficiary’s uuid, as returned on create.

Example

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

Responses

200

The beneficiary.

application/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

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
  }
}

401

Missing or invalid Basic auth credentials.

application/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

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.

application/json

object

error_code

string

error_message

string

status_code

integer

Examples

Unknown uuid

{
  "error_code": "not_found",
  "error_message": "beneficiary \"a2e0434e-17ae-41b1-a1cf-1694ad63ee99\" does not exist",
  "status_code": 404
}