User

User

Generate user authentication tokens

post

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/user/tokens

Generates authentication tokens for a user. Creates a new user if one doesn't exist with the provided email. This feature is disabled by default and can be enabled by contacting Fonbnk support.

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Body

application/json

emailstringRequired

Email of a user

Example: [email protected]

countryIsoCodestringRequired

Country code

Example: NG

Responses

200

Successfully generated user tokens

application/json

accessTokenstringOptional

JWT access token for user authentication

refreshTokenstringOptional

JWT refresh token for token renewal

post

/api/user/tokens

HTTPcURLJavaScriptPython

POST /api/user/tokens HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "email": "[email protected]",
  "countryIsoCode": "NG"
}

200

Successfully generated user tokens

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get User KYC Status

post

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/user/kyc/status

Retrieves the Know Your Customer (KYC) status for a given user. If the user does not exist, a new user will be created with the provided email and country ISO code. This feature is disabled by default and can be enabled by contacting Fonbnk support.

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Body

application/json

emailstring · emailRequired

The user's email address.

Example: [email protected]

countryIsoCodestringRequired

The ISO 3166-1 alpha-2 country code for the user.

Example: NG

Responses

200

Successfully retrieved the user's KYC status.

application/json

passedKycTypestringOptional

The type of KYC the user has passed.

Example: advanced

kycStatusstring · enumOptional

The current KYC status of the user.

Example: pendingPossible values:

kycStatusDescriptionstringOptional

A description of the KYC status.

Example: Partial Match

reachedKycLimitbooleanOptional

Indicates if the user has reached their KYC limit.

Example: false

post

/api/user/kyc/status

HTTPcURLJavaScriptPython

POST /api/user/kyc/status HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "email": "[email protected]",
  "countryIsoCode": "NG"
}

200

Successfully retrieved the user's KYC status.

{
  "passedKycType": "advanced",
  "reachedKycLimit": false,
  "kycStatus": "approved",
  "kycStatusDescription": "Partial Match",
  "basicDocuments": [
    {
      "_id": "67da909b739fc481aa525c43",
      "type": "basic",
      "title": "Voter ID",
      "value": "VOTER_ID",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "id_number": {
          "type": "string",
          "label": "ID number",
          "required": true,
          "format": "0000000000000000000",
          "regexp": "^[a-zA-Z0-9 ]{9,29}$",
          "regexpFlags": "i"
        }
      }
    },
    {
      "_id": "67da909b739fc481aa525c45",
      "type": "basic",
      "title": "BVN",
      "value": "BVN",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "id_number": {
          "type": "string",
          "label": "BVN Number",
          "required": true,
          "format": "00000000000",
          "regexp": "^[0-9]{11}$"
        }
      }
    },
    {
      "_id": "67da909b739fc481aa525c47",
      "type": "basic",
      "title": "NIN V2",
      "value": "NIN_V2",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "id_number": {
          "type": "string",
          "label": "NIN V2 Number",
          "required": true,
          "format": "00000000000",
          "regexp": "^[0-9]{11}$"
        }
      }
    },
    {
      "_id": "67da909b739fc481aa525c49",
      "type": "basic",
      "title": "NIN SLIP",
      "value": "NIN_SLIP",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "id_number": {
          "type": "string",
          "label": "NIN SLIP Number",
          "required": true,
          "format": "00000000000",
          "regexp": "^[0-9]{11}$"
        }
      }
    },
    {
      "_id": "67da909b739fc481aa525c4b",
      "type": "basic",
      "title": "Drivers license",
      "value": "DRIVERS_LICENSE",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "id_number": {
          "type": "string",
          "label": "ID number",
          "required": true,
          "regexp": "^[a-zA-Z]{3}([ -]{1})?[A-Z0-9]{6,12}$",
          "regexpFlags": "i",
          "format": "ABC000000000"
        }
      }
    }
  ],
  "advancedDocuments": [
    {
      "_id": "67da93c0dfd3a00f3380b857",
      "type": "advanced",
      "title": "Driving License",
      "value": "DRIVERS_LICENSE",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c0dfd3a00f3380b859",
      "type": "advanced",
      "title": "National IDs, Consular IDs & Diplomat IDs",
      "value": "IDENTITY_CARD",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c0dfd3a00f3380b85b",
      "type": "advanced",
      "title": "Passports",
      "value": "PASSPORT",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c0dfd3a00f3380b85d",
      "type": "advanced",
      "title": "Registration certificate",
      "value": "REGISTRATION_CERTIFICATE",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c1dfd3a00f3380b85f",
      "type": "advanced",
      "title": "Residency permits, Refugee IDs & Residency cards",
      "value": "RESIDENT_ID",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c1dfd3a00f3380b861",
      "type": "advanced",
      "title": "Border crossing documents & Visas",
      "value": "TRAVEL_DOC",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        }
      }
    },
    {
      "_id": "67da93c1dfd3a00f3380b863",
      "type": "advanced",
      "title": "Voter's Identity Card",
      "value": "VOTER_ID",
      "requiredFields": {
        "first_name": {
          "type": "string",
          "label": "First Name",
          "required": true
        },
        "last_name": {
          "type": "string",
          "label": "Last Name",
          "required": true
        },
        "dob": {
          "type": "date",
          "label": "Date of birth",
          "required": true
        },
        "email": {
          "type": "email",
          "label": "Email",
          "required": true
        },
        "images": {
          "type": "smile-identity-images",
          "label": "Verification images",
          "required": true
        },
        "kycRules": {
          "onramp": [
            {
              "min": 0,
              "max": 2,
              "type": "none"
            },
            {
              "min": 2,
              "max": 20,
              "type": "basic"
            },
            {
              "min": 20,
              "max": "Infinity",
              "type": "advanced"
            }
          ],
          "offramp": [
            {
              "min": 0,
              "max": 2,
              "type": "none"
            },
            {
              "min": 2,
              "max": 20,
              "type": "basic"
            },
            {
              "min": 20,
              "max": "Infinity",
              "type": "advanced"
            }
          ]
        }
      }
    }
  ]
}

Submit User KYC Information

post

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/user/kyc/submit

Submits Know Your Customer (KYC) information for a user. This feature is disabled by default and can be enabled by contacting Fonbnk support.

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Body

application/json

emailstring · emailRequired

The email address of the user

Example: [email protected]

documentIdstringRequired

ID of the KYC document type being submitted

Example: 60a3e5e1f5c1a40b2c9e4b2d

Responses

200

Successfully submitted KYC information

application/json

successbooleanOptionalExample: true

post

/api/user/kyc/submit

HTTPcURLJavaScriptPython

POST /api/user/kyc/submit HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "email": "[email protected]",
  "documentId": "60a3e5e1f5c1a40b2c9e4b2d",
  "userFields": {
    "first_name": "John",
    "last_name": "Doe",
    "id_number": "12345678",
    "dob": "2000-01-01T00:00:00.000Z"
  }
}

200

Successfully submitted KYC information

{
  "success": true
}