Netapps BVN Validation .
\nThis documentation will guide you through intergrating this service into your application.
\nTo begin using our API, you need to complete the Know Your Customer (KYC) process on our merchant portal. This involves providing necessary information and documentation to verify your identity and establish a business relationship with us. Once your KYC is approved, you will recieve a ClientId and ClientSecret to gain access to the API.
To make authorized API requests, you must obtain a bearer token. Start by making a request to the Get Auth endpoint using your ClientId and ClientSecret. Create a Basic authentication header by encoding your ClientId and ClientSecret, and include it in the request. The response will contain a JWT bearer token, which you should store securely. Take note that the token has an expiration time, as indicated in the response and the JWT's payload.
With the obtained bearer token, you can proceed to make calls to various API endpoints. Include the bearer token in the Authorization header of each request to authenticate your API calls.
\nExplore the different endpoints available in our API documentation. Each endpoint serves a specific purpose. Review the documentation for each endpoint to understand the required parameters, expected responses, and any additional details.
\nEnsure that your API requests adhere to the required format specified in the documentation. Most commonly, APIs use JSON or XML formats for data transmission. Verify the structure and data types of the request payload, and also be familiar with the expected format of the response.
\nBe prepared to handle potential errors returned by the API. Errors can occur due to various reasons, such as invalid requests, authentication issues, or server errors. Consult the API documentation to understand the possible error codes, their meanings, and the recommended way to handle them in your application.
\nDuring development, thoroughly test your API integration. Use different scenarios and test cases to verify that your requests are being processed correctly and that you are receiving the expected responses. Debug any issues or unexpected behaviors that you encounter.
\nOnce your integration is live, continuously monitor the performance and behavior of your API usage. Keep track of response times, error rates, and any performance bottlenecks. Optimize your implementation as needed to improve efficiency and reliability.
\nDocument your API integration to ensure future maintenance and to assist other developers who may work on the project. Keep an eye on any updates or new versions of the API that may be released, and refer to the API provider's support resources or community forums for assistance and further guidance.
\nBy following these steps, you will be able to successfully onboard, authorize, and utilize our API to integrate our services into your application or business workflow.
\nThe scope of BVN is primarily to establish and maintain a unique identity for bank customers in Nigeria. It links all the accounts of a customer in different banks using the BVN as the identifier, thus providing a centralized and reliable means of identifying customers and preventing identity theft and fraud.
\nIn summary, the BVN scope includes unique identification, KYC requirements, fraud prevention, financial inclusion, and security. It helps to improve the efficiency and security of the banking system in Nigeria.
\nThe BVN scopes and the descriptions are captured in the table below:
\nEndFragment
\nThe scope response structure is obtained by passing the scope as an array to scope property in the BVN Validation Request.
The response structures are as follows:
\n{ \n \"customer_id\" : \"\", \n \"enroll_user_name\" : \"\", \n \"gender\" : \"\", \n \"title\" : \"\", \n \"surname\" : \"\", \n \"first_name\" : \"\", \n \"middle_name\" : \"\", \n \"date_of_birth\" : \"\", \n \"face_image\" : \"\", \n \"lga_of_origin\" : \"\", \n \"marital_status\" : \"\", \n \"nationality\" : \"\", \n \"nin\" : \"\", \n \"remarks\" : \"\", \n \"state_of_origin\" : \"\", \n \"additional_info_1\" : \"\", \n \"watchlisted\" : \"\", \n}\n\n{ \n \"state_of_capture\":\"\", \n \"lga_of_capture\":\"\", \n \"enrollment_date\":\"\", \n \"enroll_bank_code\":\"221\", \n \"customer_id\":\"000395205\", \n \"name_on_card\":\"\", \n \"branch_name\":\"\", \n \"watchlisted\":\"\", \n \"serial_no\":\"\" \n}\n\n{ \n \"bvn\": \"\" \n}\n\n{ \n \"state_of_origin\": \"\", \n \"lga_of_origin\": \"\", \n \"state_of_residence\": \"\", \n \"lga_of_residence\": \"\", \n \"state_of_capture\": \"\", \n \"residential_address\": \"\" \n}\n\n{ \n \"Phone_number\": \" \" \n}\n\n{ \n \"email_address\": \"\" \n}\n\nAuthorization: IP Check and Header authorization/bearer token. The authorization details will be shared privately.
\nAfter obtaining the BVN from the user, send the request payload to the Netapps BVN validation API.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"token"}]},"isInherited":true,"source":{"_postman_id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","name":"BVN Validation","type":"collection"}},"urlObject":{"path":["api","v1","request"],"host":["https://bvn-validation.netapps.ng"],"query":[],"variable":[]}},"response":[{"id":"0fc41cd7-de6f-4559-8d92-f53799023dfe","name":"Success but with invalid records","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"sendSMS\": false,\n \"sendEmail\": false,\n \"scope\": [\n \"contact_info\"\n ], //multiple scopes can be sent\n \"callbackURL\": \"https://www.your-webhook.com/\",\n \"payload\": [\n {\n \"customerRef\": \"cusRef\",\n \"phone\": \"070230340933\",\n \"email\": \"a@b.com\",\n \"bvn\": \"2222283003\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://bvn-validation.netapps.ng/api/v1/request"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 18 Aug 2023 11:23:49 GMT"},{"key":"Server","value":"Apache/2.4.57 () OpenSSL/1.0.2k-fips PHP/8.2.3"},{"key":"Upgrade","value":"h2,h2c"},{"key":"Connection","value":"Upgrade, Keep-Alive"},{"key":"X-Powered-By","value":"AWS"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, HEAD"},{"key":"Access-Control-Allow-Headers","value":"X-Requested-With"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Content-Length","value":"188"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"msg\": \"Request submitted\",\n \"flag\": true,\n \"auth\": true,\n \"data\": {\n \"batchRef\": \"ROSRvhSnVfuY\",\n \"validRecords\": [],\n \"invalidRecords\": [\n {\n \"customerRef\": \"cusRef\",\n \"phone\": \"070230340933\",\n \"email\": \"a@b.com\",\n \"bvn\": \"2222283003\",\n \"reason\": \"BVN is invalid\",\n \"url\": \"https://bvn-validation.netapps.ng/consent/osudfuosdhf\" \n }\n ]\n }\n}"},{"id":"f4bdd1e5-25b7-4588-9c08-9d81a1b82cd4","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"sendSMS\": false,\n \"sendEmail\": false,\n \"scope\": [\n \"contact_info\"\n ], //multiple scopes can be sent\n \"callbackURL\": \"https://www.your-webhook.com/\",\n \"payload\": [\n {\n \"customerRef\": \"cusRef\",\n \"phone\": \"070230340933\",\n \"email\": \"a@b.com\",\n \"bvn\": \"2222283003\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://bvn-validation.netapps.ng/api/v1/request"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 18 Aug 2023 11:23:49 GMT"},{"key":"Server","value":"Apache/2.4.57 () OpenSSL/1.0.2k-fips PHP/8.2.3"},{"key":"Upgrade","value":"h2,h2c"},{"key":"Connection","value":"Upgrade, Keep-Alive"},{"key":"X-Powered-By","value":"AWS"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, HEAD"},{"key":"Access-Control-Allow-Headers","value":"X-Requested-With"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Content-Length","value":"188"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"msg\": \"Request submitted\",\n \"flag\": true,\n \"auth\": true,\n \"data\": {\n \"batchRef\": \"ROSRvhSnVfuY\",\n \"validRecords\": [\n {\n \"customerRef\": \"cusRef\",\n \"phone\": \"070230340933\",\n \"email\": \"a@b.com\",\n \"bvn\": \"22222830030\",\n \"url\": \"https://bvn-validation.netapps.ng/consent/osudfuosdhf\" \n }\n ],\n \"invalidRecords\": []\n }\n}"}],"_postman_id":"044eec42-129a-43d3-890c-7b71cb09f80e"},{"name":"Status","id":"9377c667-88d7-4327-9211-1b4495212fd0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://bvn-validation.netapps.ng/api/v1/status?batchRef=jAZqfBCoicDk","description":"Authorization: IP Check and Header authorization/bearer token. The authorization details will be shared privately.
\nNote: The bvn_data in the response will vary depending on the requested scope
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"token"}]},"isInherited":true,"source":{"_postman_id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","name":"BVN Validation","type":"collection"}},"urlObject":{"path":["api","v1","status"],"host":["https://bvn-validation.netapps.ng"],"query":[{"key":"batchRef","value":"jAZqfBCoicDk"}],"variable":[]}},"response":[{"id":"7b788d75-5107-4adc-893c-32f6eabc592f","name":"Success","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://bvn-validation.netapps.ng/api/v1/status?batchRef=jAZqfBCoicDk","host":["https://bvn-validation.netapps.ng"],"path":["api","v1","status"],"query":[{"key":"batchRef","value":"jAZqfBCoicDk"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 18 Aug 2023 10:54:51 GMT"},{"key":"Server","value":"Apache/2.4.57 () OpenSSL/1.0.2k-fips PHP/8.2.3"},{"key":"Upgrade","value":"h2,h2c"},{"key":"Connection","value":"Upgrade, Keep-Alive"},{"key":"X-Powered-By","value":"AWS"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, HEAD"},{"key":"Access-Control-Allow-Headers","value":"X-Requested-With"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Content-Length","value":"639"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"msg\": \"Data retrieved\",\n \"flag\": true,\n \"auth\": true,\n \"data\": [\n {\n \"bvn\": \"22222988585\",\n \"email\": \"alextech4all@gmail.com\",\n \"phone\": \"2347034477744\",\n \"status\": \"PENDING\",\n \"bvn_data\": []\n },\n {\n \"bvn\": \"22222988584\",\n \"email\": \"a.ebere@gmail.com\",\n \"phone\": \"2347034477723\",\n \"status\": \"PENDING\",\n \"bvn_data\": {\n \"bvn\": \"22222988584\",\n \"state_of_capture\": \"Imo State\",\n \"lga_of_capture\": \"Owerri Municipal\",\n \"enrollment_date\": \"10-Apr-2015\",\n \"enroll_bank_code\": \"058\",\n \"customer_id\": \"256111132\",\n \"name_on_card\": \"EBERE NNAMDI BETHEL\",\n \"branch_name\": \"OWERRI\",\n \"watchlisted\": 0,\n \"serial_no\": 8123111\n }\n },\n {\n \"bvn\": \"22351895016\",\n \"email\": \"\",\n \"phone\": \"2347035537527\",\n \"status\": \"PENDING\",\n \"bvn_data\": []\n }\n ]\n}"}],"_postman_id":"9377c667-88d7-4327-9211-1b4495212fd0"},{"name":"Notification To Your Callback URL","id":"a8db7fb3-fb5b-4dcc-bd99-e4576622d5af","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"ref\": \"sjdgayuasd\",\n \"customerRef\": \"sdifhsdkjf\",\n \"data\": {\n ...bvn_data\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://www.your-webhook.com/","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"token"}]},"isInherited":true,"source":{"_postman_id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","id":"05f514ab-c3c6-48ae-890d-8d4a7701c500","name":"BVN Validation","type":"collection"}},"urlObject":{"protocol":"https","path":[""],"host":["www","your-webhook","com"],"query":[],"variable":[]}},"response":[{"id":"2e99b418-12f9-4acd-a875-b5d5a3d0500b","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"ref\": \"sjdgayuasd\",\n \"customerRef\": \"sdifhsdkjf\",\n \"data\": {\n ...bvn_data\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://www.your-webhook.com/"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"a8db7fb3-fb5b-4dcc-bd99-e4576622d5af"}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"token"}]}},"event":[{"listen":"prerequest","script":{"id":"d0e4da39-3574-42a2-8f3f-d378ac704339","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"a55047cc-78ea-4e38-8213-a5fb73276e6f","type":"text/javascript","exec":[""]}}],"variable":[{"key":"bearer","value":"token","type":"string"},{"key":"baseURL","value":"https://bvn-validation.netapps.ng","type":"string"},{"key":"baseURL","value":"http://bvn-validation.netapps.local","type":"string","disabled":true}]}