Get User Details

Retrieves the details of a specific user associated with the merchant.

This endpoint returns the user's basic information, account status, KYC status and tier information, as well as any transaction limits configured for the user.

Endpoint

GET /api/v1/merchant/user

Headers

Header	Description	Required
`x-merchant-ref`	Unique reference identifying the merchant	Yes

Query Parameters

Parameter	Description	Required
`user_ref`	Unique reference identifying the user	Yes

Request

curl --location -g '{{base_url}}/api/v1/merchant/user?user_ref={{vault%3AUser-ref}}' \
--header 'x-merchant-ref: {{vault\:x-merchant-ref}}'

Response

{
  "status": "success",
  "message": "User details fetched",
  "data": {
    "user_ref": "UREF046DAD90CCEA46A3B2866792B65850E9009OV",
    "name": "Teslim Ayantola",
    "email": "[email protected]",
    "status": "APPROVED",
    "kyc": {
      "status": "NOT_STARTED",
      "current_tier": 0,
      "tiers": [
        {
          "tier": 1,
          "status": "NOT_STARTED"
        },
        {
          "tier": 2,
          "status": "NOT_STARTED"
        },
        {
          "tier": 3,
          "status": "NOT_STARTED"
        }
      ]
    },
    "transaction_limits": []
  }
}

Response Fields

Field	Description
`status`	Indicates whether the request was successful.
`message`	Describes the result of the request.
`data.user_ref`	Unique reference assigned to the user.
`data.name`	Full name of the user.
`data.email`	Email address associated with the user.
`data.status`	Current status of the user's account.
`data.kyc.status`	Overall KYC status of the user.
`data.kyc.current_tier`	The user's current KYC tier.
`data.kyc.tiers`	Lists the available KYC tiers and the user's status for each tier.
`data.kyc.tiers[].tier`	Identifies the KYC tier.
`data.kyc.tiers[].status`	Indicates the user's status for the specific KYC tier.
`data.transaction_limits`	Contains the transaction limits configured for the user. An empty array indicates that no transaction limits are currently returned for the user.

KYC Information

The kyc object provides the user's KYC progression.

current_tier shows the highest KYC tier currently reached by the user.
tiers provides the status of each available KYC tier.
A tier can have its own status independently of the overall KYC status.

For example:

"kyc": {
  "status": "NOT_STARTED",
  "current_tier": 0,
  "tiers": [
    {
      "tier": 1,
      "status": "NOT_STARTED"
    },
    {
      "tier": 2,
      "status": "NOT_STARTED"
    },
    {
      "tier": 3,
      "status": "NOT_STARTED"
    }
  ]
}

In this example, the user has not started KYC and has not reached any KYC tier.

Transaction Limits

The transaction_limits field contains the transaction limits applicable to the user.

"transaction_limits": []

An empty array means that no transaction-limit records are currently returned for the user.

When limits are configured, this field can be used to retrieve the limits applicable to the user's transactions.

Use Cases

The Get User endpoint can be used to:

Retrieve a user's profile information.
Check whether a user account is approved.
Check the user's KYC status.
Determine the user's current KYC tier.
Check the status of individual KYC tiers.
Retrieve transaction limits associated with the user.
Verify user information before initiating user-specific operations.