Notification URL/Webhook

A notification URL, also known as a webhook URL, is a URL endpoint that is used in web development to receive notifications from an external system. When an event or action occurs in the external system, such as a payment being made or a user account being updated, the system will send a notification to the callback URL to inform the receiving system of the event.

Response will be sent to the callbackURL passed in the request for each BVN in the payload. The following are possible response data structures to expect;

Request Method: POST; RAW POST DATA, Content-Type: application/json

Success Payload

{ 
  "flag": true, 
  "msg": "Data retrieved", 
  "data": { 
    "ref" : "a76ce6Tz11Pq", 
    "bvn": "21234123456", 
    "phone": "07034477723", 
    "email": "[email protected]", 
    "bvn_data": { 
      "customer_id" : "", 
      "enroll_user_name" : "", 
      "gender" : "", 
      "title" : "", 
      "surname" : "", 
      "first_name" : "", 
      "middle_name" : "", 
      "date_of_birth" : "", 
      "face_image" : "", 
      "lga_of_origin" : "", 
      "marital_status" : "", 
      "nationality" : "", 
      "nin" : "", 
      "remarks" : "", 
      "state_of_origin" : "", 
      "additional_info_1" : "", 
      "watchlisted" : "", 
    } 
  }
}

Payload Description:

Above is a sample of a success payload that will be emitted to your callbackURL with the BVN data when a consent is given by the user. The payload includes a status flag: flag (Bool), Message: msg (String), and the response data: data; This is an Object containing the reference generated when the request was made ref (String), the supplied user’s bvn, phone (String) & email (String) and the BVN Data bvn_data (Object) scoped to PROFILE DATA

Error Payload (Invalid BVN)

{ 
  "flag": false, 
  "msg": "Invalid request", 
  "data": { 
    "ref" : "a76ce6Tz11Pq", 
    "bvn": "21234", 
    "phone": "07034477723", 
    "email": "[email protected]", 
    "error_code": "0001", 
    "reason": "Invalid BVN supplied" 
  } 
}

Payload Description:

Above is a sample of an error payload that will be emitted to your callbackURL if the supplied BVN is invalid. The payload includes a status flag: flag (Bool), Message: msg (String), and the response data: data; This is an Object containing the reference generated when the request was made ref (String), the supplied user’s bvn, phone (String) & email (String) error code error_code (String) and reason reason (String)

🚧

Note

BVN is only valid as an 11-digit number

Error Payload (Invalid email & phone number)

{ 
  "flag": false, 
  "msg": "Invalid request", 
  "data": { 
    "ref" : "a76ce6Tz11Pq", 
    "bvn": "21234", 
    "phone": "0734477T23", 
    "email": "useremail@mail.", 
    "error_code": "0002", 
    "reason": "email and phone number is invalid" 
  } 
}

Payload Description:

Above is a sample of an error payload that will be emitted to your callbackURL if the supplied email and phone number is invalid, it is required to have a valid email and/or phone number in your request for the user to receive the BVN consent request.

The payload includes a status flag: flag (Bool), Message: msg (String), and the response data: data; This is an Object containing the reference generated when the request was made ref (String), the supplied user’s bvn, phone (String) & email (String) error code error_code (String) and reason: reason (String)

🚧

Note

Phone number is only valid in the following formats 07034477723, 7034477723, 2347034477723, +2347034477723

Error Payload (User didn't respond)

{ 
  "flag": false, 
  "msg": "User didn't respond", 
  "data": { 
    "ref" : "a76ce6Tz11Pq", 
   "bvn": "21234123456", 
   "phone": "07034477723", 
   "email": "[email protected]", 
   "error_code": "0003", 
   "reason": "Failed to get user's consent after 3 tries" 
  } 
}

Payload Description:

Above is a sample of an error payload that will be emitted to your callbackURL if the user did not respond to the consent request.

The payload includes a status flag: flag (Bool), Message: msg (String), and the response data: data; This is an Object containing the reference generated when the request was made ref (String), the supplied user’s bvn, phone (String) & email (String) error code error_code (String) and reason reason (String)

🚧

Note

The system will retry 3 times before this event is emitted.

Error Payload (User denied consent)

{ 
  "flag": false, 
  "msg": "User denied consent", 
  "data": { 
    "ref" : "a76ce6Tz11Pq", 
    "bvn": "21234123456", 
    "phone": "07034477723", 
    "email": "[email protected]", 
    "error_code": "0004", 
    "reason": "User declined to give consent" 
  } 
}

Payload Description:

Above is a sample of an error payload that will be emitted to your callbackURL if the user declines the consent request.

The payload includes a status flag: flag (Bool), Message: msg (String), and the response data: data; This is an Object containing the reference generated when the request was made ref (String), the supplied user’s bvn, phone (String) & email (String) error code error_code (String) and reason reason (String)

🚧

Note

The system will not retry if the user declines the consent.