Getting Started

This is the Getting STarted page for KYC

We have provided a list of endpoints to make the integration and onboarding seamless.

KYC Flow

1. Register your app on the registration endpoint

2. Verify your app using the verify endpoint

3. Get the appropriate KYC type (individual, business)

4. Create a KYC Order or Request (individual, business)

5. Get KYC URL where your user is redirected to perform KYC

6. Get KYC notification on your registered callback.

7. Your end user is approved or rejected.

8. Get user data/KYC status to confirm your user's KYC status.

Getting Started

App Registration Endpoint

This endpoint is to register an app

POST https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/app/register

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Name	Type	Description
name	String	The name of your app
email	String	The email of the company
origin	Array	The domains you are calling from. this is whitelisted. eg "http://localhost:5179"

200: OK

{
  "message": "Verification token sent successfully",
  "value": "123456",
  "app": {
    "email": "[e-mail]",
    "name": "Flutterwave",
    "origin": [
      "http://localhost:5179"
    ],
    "verified": false,
    "status": "Active",
    "_id": "66053d262d3f43787be1e1a6",
    "created_at": "2024-03-28T09:49:26.674Z",
    "updated_at": "2024-03-28T09:49:26.752Z",
    "__v": 0
  }
}

400

Key	Type	Description	Value
message	String	This message says there is a verification token (6 digits) which has be sent to the email used on the register endpoint	e.g 123456
value	String	This is the verification token this has also been sent to your email.	e.g 123456
app	Object	This is an object describing the opp that just registered on the app register endpoint	{ "email": "[e-mail]", "name": "Flutterwave", "origin": [ "http://localhost:5179", "https://include-stage-89c7b78dfc34.herokuapp.com/" ], "verified": false, "status": "Active", "_id": "66053d262d3f43787be1e1a6", "created_at": "2024-03-28T09:49:26.674Z", "updated_at": "2024-03-28T09:49:26.752Z", "__v": 0 }
verified	String	Verified means if the app has verified on the app verify endpoint using the verification Token	True/False
status	String	This is your app's status on our endpoint	Active/Inactive
_id	String	This is your app's ID on our system. App ID' s
created_at	Datetime	this is the time your app was registered on the KYC system
updated_at	Datetime	This is the last time a value was updated on your app's data

Example request- Code.

Nodejs

const fetch = require('node-fetch');

fetch("https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/OnboardPartner", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "name": "Binance",
    "email": "[e-mail]",
    "origin": ["", ""]
  }
})
  .then(response => console.log(response))
  .catch(err => console.error(err));

cURL

curl "https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/OnboardPartner" \
  -H 'Content-Type: application/json' \
  -X POST \
  -b 'connect.sid'='s%3AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%2Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs' \
  -d '{
  "partner_code": "Binance",
  "email": "[e-mail]"
}' 

App Activate/Verify Endpoint

This is used to verify an app

POST https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/app/verify

Request Body

Name	Type	Description
email	String	this is the email used to register your app
code	String	This is the verification token sent to your email

200: OK Successful

{
  "message": "Token verification successful",
  "data": {
    "_id": "66053d262d3f43787be1e1a6",
    "email": "[e-mail]",
    "name": "Flutterwave",
    "origin": [
      "http://localhost:5179",
      "https://include-stage-89c7b78dfc34.herokuapp.com/"
    ],
    "created_at": "2024-03-28T09:49:26.674Z",
    "updated_at": "2024-03-28T09:50:50.303Z",
    "__v": 0
  }
}

400: Bad Request Error

{
     error: true,
     message: string,
     data: null
     }

Request Verification Token

This endpoint is used by 3rd party to get verification Token

POST https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/request

The verification token will be sent to the email address

Headers

Name	Type	Description
Content-type*	String	application/json

Request Body

Name	Type	Description
email*	String	[e-mail]

200: OK

{
  "message": "Verifiection token sent successfully",
  "value": "123456"
}

Example Request- Code

Node

const fetch = require('node-fetch');

fetch(" 
https://fuspay-kyc-ms-df741b092e53.herokuapp.com/api/v1
/request", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
  },
  "body": {
    "email": "[e-mail]",
  }
})
  .then(response => console.log(response))
  .catch(err => console.error(err));

Get KYC Type

GET https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/kyc_type/

This endpoint is used to get an Array of KYC types (Business, Individual). This provided the _id of the KYC that would be used when creating a KYC request

Headers

Name	Type	Description
Content-type*	String	application/json

Request Body

Name	Type	Description
curl --location	String	This enables curl to follow HTTP redirects automatically.

200: OK

[
  {
    "_id": "6564dc907049168cd3eeab8e",
    "flow_id": "6551e7065c98f8001cee0fc2",
    "name": "Individual",
    "created_at": "2023-11-27T18:14:40.904Z",
    "updated_at": "2023-11-27T18:14:40.904Z",
    "__v": 0
  }
]

Key	Type	Description	Value
id	String	This is the id that represents the KYC (Business, Individual) .	e.g. 5b47837d7839e9d9dyd93997d939
flow_id	String	The flow id represents the specific flow of the KYC. e.g. KYC for individuals can have different flows	e.g. 6a3636e63848r838383478w8
name	String	This describes the kind of KYC e.g. Individual.	individual/business

Create Order Endpoint

Create Order Endpoint for Individual

This endpoint is used to create a KYC order for an individual

POST https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/order/

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Key	Type	Description
full_name	String	The user full name to create the KYC
email	String	The user email to create the KYC
phone	String	The phone number to create the KYC
app	String	This is your app's ID
kyc_type	String	This is a string representing the KYC type. Each KYC type has an identifier
callback	String	A webhook where notifications from us would be posted to
redirect	String	This is a URL where we would redirect your users after they have completed the KYC journey.
reference	String	This is an identifier for your user from your end.

200: OK successful response

{
  "_id": "660c1000ed806b0874954140",
  "app": "66053d262d3f43787be1e1a6",
  "kyc_type": {
    "_id": "65cc97ef7aef3a4c06747dfe",
    "name": "Individual",
    "created_at": "2024-02-14T10:37:35.637Z",
    "updated_at": "2024-02-14T10:37:35.637Z",
    "__v": 0
  },
  "scan_ref": "",
  "verification_url": "http://localhost:5173/verification/individual/660c1000ed806b0874954140",
  "callback": "https://custom-webhook-app-8b6d54acde1c.herokuapp.com/api/payload",
  "reference": "1234",
  "redirect": "https://custom-webhook-app-8b6d54acde1c.herokuapp.com",
  "created_at": "2024-04-02T14:02:40.628Z",
  "updated_at": "2024-04-02T14:02:40.640Z",
  "__v": 0
}

400: Bad Request failed responses

Response Body

Key	Type	Description	Value
_id	String	This is the identifier representing the request sent to the KYC create request endpoint
app	String	This is your app's ID
kyc_type	Object	An object containing info about the KYC performed
_id	String	the id of the KYC type
name	String	the type of KYC that was performed.	Individual/Business
verification_url	String	this is the link where your user is redirected to go and perform the KYC
callback	String	This is the URL where KYC status of your user would be posted after they have completed the KYC journey
redirect	String	This is the URL where your user would be redirected after KYC.

Example Request- Code

Nodejs

cURL

Create Order Endpoint for Business

This endpoint is used to create a KYC order for a business

POST https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/business/order

Name	Type	Description
Content-Type*	String	application/json

Request Body

{
    "business_name": "Springbok 9",
    "country": "Nigeria",
    "business_email": "[e-mail]",
    "app": "{{kyc_app_id}}",
    "kyc_type": "{{kyc_type_id}}",
    "callback": "https://webhook.site/29e10900-6a6d-4663-b2d9-def37b0768d9",
    "reference": "1234",
    "redirect": "https://webhook.site/29e10900-6a6d-4663-b2d9-def37b0768d9",
    "custom_files": ["Birth Certificate", "NIN"],
    "state_of_jurisdiction": "Indonesia"
}

Key	Type	Description
business_name	String	The name of the business to be KYCed
country	String	The country of the business of be KYCed
business_email	String	This is the email of the business you are trying to do KYC for
app	String	This is your app's ID
kyc_type	String	This is a string representing the KYC type. Each KYC type has an identifier
callback	String	A webhook where notifications from us would be posted to
redirect	String	This is a URL where we would redirect your users after they have completed the KYC journey.
reference	String	This is an identifier for your user from your end.
custom_files	Array	This is an array containing a list of extra/custom files you would like to be collected from the business
state_of_jurisdiction	String	This is the country the business was incorporated in.

200: OK successful response

{
  "_id": "65dfee0ee6198e7a89765cfa",
  "app": "65cc972b458f23f853670917",
  "business_name": "Fuspay Technologies",
  "country": "Nigeria",
  "business_email": "[e-mail]",
  "kyc_type": {
    "_id": "65de68871f07994754c3db87",
    "name": "Business",
    "created_at": "2024-02-27T22:56:07.010Z",
    "updated_at": "2024-02-27T22:56:07.010Z",
    "__v": 0
  },
  "verification_url": "http://localhost:5173/verification/business/65dfee0ee6198e7a89765cfa",
  "reference": "1234",
  "redirect": "https://webhook.site/29e10900-6a6d-4663-b2d9-def37b0768d9",
  "custom_files": [],
  "created_at": "2024-02-29T02:38:06.033Z",
  "updated_at": "2024-02-29T02:38:06.052Z",
  "__v": 0,
  "order": {
    "_id": "65dfee0ee6198e7a89765cfc",
    "progress": [],
    "error": [],
    "status": "Unprocessed",
    "kyc_token": "",
    "created_at": "2024-02-29T02:38:06.047Z",
    "updated_at": "2024-02-29T02:38:06.063Z",
    "__v": 0
  }
}

400: Bad Request failed responses

Response Body

Key	Type	Description	Value
_id	String	id representing the business that has been KYCed on the KCY system
app	String	This is your app's ID
kyc_type	Object	An object containing info about the KYC performed
_id	String	the id of the KYC type eg individual or businesses
name	String	the type of KYC that was performed.	Individual/Business
verification_url	String	this is the link where your user is redirected to go and perform the KYC
callback	String	This is the URL where KYC status of your user would be posted after they have completed the KYC journey
redirect	String	This is the URL where your user would be redirected after KYC.
custom_files	Array	an Array containing the custom files to be collected from the business
order	Object	This is an object containing details of the KYC request/order
_id	String	this is an id presenting the KYC request itself
status	String	The status of the order

Get Callbacks

GET https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/responses

Headers

Name	Type	Description
Content-type*	String	application/json

Request Body

Name	Type	Description
curl --location --request OPTIONS	String	follows HTTP redirects and specifically sends an HTTP OPTIONS request.

Init

{
  "status": "init",
  "event": "applicantCreated",
  "order": "6687e2a3d49fe128f868203f",
  "timestamp": "2024-07-05T12:10:20.741Z",
  "kyc_token": "",
  "account": "6687e2a3d49fe128f868203d",
  "user_reference": "914a7ba2-fba8-44b7-a30c-9b332b4ce630",
  "meta_data": {
    "kyc_note": "The user is being created and KYC process is initiated.",
    "kyc_status": "awaiting_approval"
  },
  "first_name": "",
  "last_name": "",
  "phone": "",
  "email": "",
  "country": ""
}

Started

{
  "status": "init",
  "event": "applicantPersonalInfoChanged",
  "order": "6687e2a3d49fe128f868203f",
  "timestamp": "2024-07-05T12:10:20.741Z",
  "kyc_token": "",
  "account": "6687e2a3d49fe128f868203d",
  "user_reference": "914a7ba2-fba8-44b7-a30c-9b332b4ce630",
  "meta_data": {
    "kyc_note": "The user is being created and KYC process is initiated.",
    "kyc_status": "awaiting_approval"
  },
  "first_name": "",
  "last_name": "",
  "phone": "",
  "email": "",
  "country": ""
}

Pending

{
  "status": "pending",
  "event": "applicantPending",
  "order": "66881ff8884ff64fd2af95e6",
  "timestamp": "2024-07-05T16:55:45.240Z",
  "kyc_token": "",
  "account": "66881ff8884ff64fd2af95e4",
  "user_reference": "flw-app-001",
  "meta_data": {
    "kyc_note": "A user has uploaded the required documents and their status changed to Pending.",
    "kyc_status": "awaiting_approval"
  },
  "first_name": "",
  "last_name": "",
  "phone": "",
  "email": "",
  "country": ""
}

Completed

{
  "status": "completed",
  "event": "applicantReviewed",
  "order": "66881ff8884ff64fd2af95e6",
  "timestamp": "2024-07-05T16:56:15.191Z",
  "kyc_token": "",
  "account": "66881ff8884ff64fd2af95e4",
  "user_reference": "flw-app-001",
  "meta_data": {
    "kyc_note": "Verification is complete.",
    "kyc_status": "approved"
  },
  "first_name": "",
  "last_name": "",
  "phone": "",
  "email": "",
  "country": ""
}

User Data

{
  "status": "completed",
  "event": "applicantReviewed",
  "order": "66881ff8884ff64fd2af95e6",
  "timestamp": "2024-07-05T16:56:22.889Z",
  "kyc_token": "",
  "account": "66881ff8884ff64fd2af95e4",
  "user_reference": "flw-app-001",
  "meta_data": {
    "kyc_note": "Verification is complete and user's data is being returned",
    "kyc_status": "approved"
  },
  "first_name": "Timilehin",
  "last_name": "Abodunrin",
  "phone": "[phone]",
  "email": "[e-mail]",
  "country": "NGA"
}

Key	Type	Description	Value
Status	String	refers to the current phase of an order.	initialized, started, pending or completed
Event	String	events are key actions in the KYC process, such as submission, review, or approval, that affect the order's progress and outcome.	submission, review, or approval
Order	String	It is a unique identifier assigned to a specific KYC order
Timestamp	String	It is a record of the date and time when a specific event occurred
Kyc_token	String	It is a unique token used to authenticate KYC processes
Account	String	It is used to uniquely reference and manage an individual's or entity's KYC profile within the system
User_reference	String	It is a unique identifier assigned to a user specifically to managae KYC processes.
Mega_data	Array	metadata helps in tracking, managing, and providing context to the KYC process.	KYC Note, KYC Status
First_name	String	This is the first name of the customer
Last_name	String	This is the last name of the customer
Phone	String	This is the customer's phone number
Email	String	This is the Customer's Email Address
Country	String	This is the customer's country

Get Verification Status and User's Data

GET https://fuspay-kyc-prod-e9eb4fd3aa33.herokuapp.com/api/v1/order/verification-status

This endpoint is used to know the KYC status of your user. Where they are in the KYC Journey.

Headers

Name	Type	Description
Content-type*	String	application/json

Query Params

Name	Description
app_id	This is your app's ID
user_reference	This is your user's reference from your system

200: OK

{
  "status": "UNPROCESSED",
  "user_facial_images": {
    "image_1": "",
    "image_2": ""
  },
  "_id": "6687e6b301dd50bc5e48af12",
  "email": "[e-mail]",
  "full_name": "Ndoh Joel",
  "phone": "08113372866",
  "app": "667884fafdd3466dbf7c5fa4",
  "kyc_type": "6675bf35dbeea1617aaad262",
  "scan_ref": "",
  "verification_url": "http://localhost:5173/verification/individual/6687e6b301dd50bc5e48af12",
  "callback": "https://custom-webhook-app-8b6d54acde1c.herokuapp.com/api/payload",
  "reference": "cee4d97b-c90b-425f-a902-0883b4b142ca",
  "redirect": "",
  "address": "",
  "bvn": "",
  "country": "",
  "govt_id_no": "",
  "govt_id_photo": "",
  "proof_of_address": "",
  "bank_statement": "",
  "user_indemnity": "",
  "guarantors_form": "",
  "id_of_guarantor": "",
  "guarantors_proof_of_address": "",
  "created_at": "2024-07-05T12:27:31.958Z",
  "updated_at": "2024-07-05T12:27:31.971Z",
  "__v": 0,
  "order": {
    "_id": "6687e6b301dd50bc5e48af14",
    "progress": [],
    "error": [],
    "status": "UNPROCESSED",
    "kyc_token": "",
    "created_at": "2024-07-05T12:27:31.966Z",
    "updated_at": "2024-07-05T12:27:31.966Z",
    "__v": 0
  }
}

400

{
  "status": "UNPROCESSED"
}

Key	Type	Description	Value
status	String	refers to the current state of the KYC process for an individual or business	UNPROCESSED
user's_facial_images	Array	These are the images of the user's face
_id	String	The identity number used to recognize and track the user in the verification process.
email	String	email of the user
full_name	String	full name of the user
phone	String	phone number of the user
app	String	This is your apps id
kyc_type	String	This is a string representing the KYC type. Each KYC type has an identifier
scan_ref	String	reference number or identifier that is associated with the verification process
verification_url	String	this is the link where your user is redirected to go and perform the KYC	http://localhost:5173/verification/individual/6687e6b301dd50bc5e48af12
callback	String	This is the URL where KYC status of your user would be posted after they have completed the KYC journey	https://custom-webhook-app-8b6d54acde1c.herokuapp.com/api/payload
reference	String	This is an identifier for your user from your end.	e.g. cee4d97b-c90b-425f-a902-0883b4b142ca
redirect	String	This is a URL where we would redirect your users after they have completed the KYC journey.
address	String	This is the house address of the user
bvn	String	This is the bank verification number of the user
country	String	This is the user's country
govt_id_no	String	This is the government identity number of the user
govt_id_photo	String	This is the user's government id photo
proof_of_address	String	This is the user's proof of address
bank_statement	String	This is the bank statement of the user
user_indemnity	String	This is the user's agreement to cover losses or liabilities from their actions. 4o
guarantors_form	String	This is the document where guarantors agree to cover obligations if the primary party defaults
id_of_guarantor	String	This is the id of the guarantor
guarantors_proof_of_address	String	This is the guarantors proof of address
created_at	Datetime	this is the time your app was registered on the KYC system	e.g. 2024-07-05T12:27:31.958Z
updated_at	Datetime	This is the last time a value was updated on your app's data	e.g. 2024-07-05T12:27:31.971Z
__v	Number
order	Array	A request to initiate the verification process or to check the status of a user's data.