Dry-run a payment against a beneficiary's KYC

GET

/api/global/beneficiaries/{uuid}/kyc-eligibility

cURL

curl "https://api.payhero.africa/api/global/beneficiaries/a2e0434e-17ae-41b1-a1cf-1694ad63ee99/kyc-eligibility?currency=KES&amount_usd=15" \
  -u "API_USERNAME:API_PASSWORD"

Answers “would this payment clear?” without moving money. Use it before charging, or to decide whether to prompt the counterparty for more KYC.

Authorizations

basicAuth

Parameters

Path Parameters

uuid

required

string format: uuid

The beneficiary’s uuid, as returned on create.

Example

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

Query Parameters

currency

required

string

ISO 4217 currency of the intended transaction.

Example

KES

amount_usd

required

number

Intended transaction amount, in USD equivalent.

Example

Responses

200

The verdict. Note that a refusal is still a 200 — read eligible.

application/json

object

beneficiary

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

currency

string

amount_usd

number

eligible

boolean

reason

Present only when eligible is false.

string

Examples

{
  "beneficiary": {
    "uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99",
    "kyc_level": "tier_0"
  },
  "currency": "KES",
  "amount_usd": 15,
  "eligible": true
}

{
  "beneficiary": {
    "uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99",
    "kyc_level": "tier_0"
  },
  "currency": "NGN",
  "amount_usd": 15,
  "eligible": false,
  "reason": "full KYC information is required for the transaction"
}

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
}