Create KYC

Initiate KYC verification for a user by selecting the KYC tier they need to complete.

This endpoint creates a KYC verification session and returns a unique verification URL. The merchant should redirect the user to this URL to complete the required KYC process.

The KYC tier selected determines the information and verification requirements the user must complete. Before initiating KYC, use the Get KYC Tiers endpoint to understand the requirements and feature access available for each tier.

Request

To create a KYC verification session for a user, send a POST request with the user's user_ref, the KYC tier to be completed, and the required user information.

POST {{base_url}}/api/v1/user/kyc

Request Headers

Name	Type	Description
`Authorization`*	String	`Bearer ${api_key}` — your activated merchant API key.
`x-merchant-ref`*	String	Your unique merchant reference.

Request Body

Name	Type	Description
`user_ref`*	String	Unique reference identifying the user undergoing KYC verification.
`kyc_type`*	String	KYC tier to be completed, for example `tier_2`.
`phone`*	String	Phone number of the user.
`country`*	String	Country code of the user, for example `NG` for Nigeria.
`tag`*	String	Identifier for the KYC service or provider associated with the verification.

Sample Request

{
  "user_ref": "UREFB71CBD5EE4AEFB0A1587839EAD87D007QQ",
  "kyc_type": "tier_2",
  "phone": "08064642044",
  "country": "NG",
  "tag": "OMANGA"
}

Response

`200 OK`

{
  "status": "success",
  "message": "Kyc verification link created",
  "data": {
    "verification_id": "6a96eea6a38eabdb2bf77488",
    "verification_url": "https://transid2.fuspay.finance/?verificationId=6a96eea6a38eabdb2bf77488",
    "reference": "VRF_7539b619-5d44-4284-aa4e-d53b577e6f22"
  }
}

Response Fields

Key	Type	Description
`status`	String	Indicates the result of the request.
`message`	String	Message describing the result of the KYC initiation.
`data`	Object	Contains the details of the created KYC verification session.
`data.verification_id`	String	Unique identifier for the KYC verification session.
`data.verification_url`	String	URL that redirects the user to the KYC verification process.
`data.reference`	String	Unique reference for the KYC verification request.

Redirect the User to the Verification URL

After successfully creating the KYC session, use the verification_url returned in the response to direct the user to the KYC verification process.

For example:

Create KYC → Receive verification_url → Redirect User → User Completes KYC

The merchant does not need to build the KYC verification interface themselves. The returned verification URL takes the user to the KYC process associated with the selected tier.

The verification_id and reference should be retained so the verification request can be identified during subsequent KYC operations.

Updated about 2 months ago

Did this page help you?