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"

{
  "message": "Verification token sent successfully",
  "value": "123456",
  "app": {
    "email": "support@flw.com",
    "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
  }
}
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": "support@flw.com",
    "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.

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": "sample@example.com",
    "origin": ["", ""]
  }
})
  .then(response => console.log(response))
  .catch(err => console.error(err));

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

{
  "message": "Token verification successful",
  "data": {
    "_id": "66053d262d3f43787be1e1a6",
    "email": "support@flw.com",
    "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
  }
}

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

sample@example.com

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

Example Request- Code

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": "sample@example.com",
  }
})
  .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.

[
  {
    "_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.

{
  "_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
}

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

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": "joel.n@yarn.us",
    "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.

{
  "_id": "65dfee0ee6198e7a89765cfa",
  "app": "65cc972b458f23f853670917",
  "business_name": "Fuspay Technologies",
  "country": "Nigeria",
  "business_email": "joel.n@fuspay.us",
  "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
  }
}

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.

{
  "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": ""
}

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

{
  "status": "UNPROCESSED",
  "user_facial_images": {
    "image_1": "",
    "image_2": ""
  },
  "_id": "6687e6b301dd50bc5e48af12",
  "email": "joeltimmy7@gmail.com",
  "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
  }
}
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

callback

String

This is the URL where KYC status of your user would be posted after they have completed the KYC journey

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.

Last updated