API Documentation for account_management.php

This documentation outlines the functionality and usage of the account_management.php endpoint, which provides core functionalities for checking account availability and registering new accounts.

---

1. Overview

The account_management.php file acts as a single endpoint for multiple account-related API actions. All interactions with this endpoint are handled via HTTP POST requests. The requested action is determined by the action parameter in the request body.

---

2. Endpoints

The file exposes two distinct endpoints, each triggered by a specific action parameter value.

2.1. Endpoint: check_account_exists

This endpoint allows clients to check if a specific username or phone number is already registered in the system. This is typically used for real-time validation during form filling.

• Method: POST
• URL: /path/to/your-file.php
• Request Format: application/json or application/x-www-form-urlencoded

Request Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be check_account_exists.
field_type	string	Yes	The type of field to check. Can be phoneNo or username.
username_or_account	string	Yes	The value to check (either a phone number or a username).

Example cURL Request

curl --location --request POST 'https://your-domain.com/path/to/account_management.php' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "check_account_exists",
    "field_type": "phoneNo",
    "username_or_account": "08012345678"
}'

Response Format

• Success: A JSON object with status: "success" and a boolean found field.

  {
      "status": "success",
      "found": false,
      "message": "Phone number is available"
  }

• Error: A JSON object with status: "error" and a descriptive message.

  {
      "status": "error",
      "message": "Invalid phone format"
  }

---

2.2. Endpoint: register_account

This endpoint handles the complete process of registering a new user account, including validation of a provided fintech token.

• Method: POST
• URL: /path/to/your-file.php
• Request Format: application/x-www-form-urlencoded (for standard form submission) or multipart/form-data if uploading files.

Request Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be register_account.
csrf_token	string	Yes	The Cross-Site Request Forgery token from the form.
token_verification	string	Yes	The Fintech verification token to validate the request.
firstName	string	Yes	The user's first name.
lastName	string	Yes	The user's last name.
phoneNo	string	Yes	An 11-digit phone number.
username	string	Yes	A unique username (3-20 characters, letters, numbers, and underscores).
email	string	Yes	The user's email address.
pass	string	Yes	The user's password (min. 8 characters with letters and numbers).
pin	string	Yes	A 4-digit PIN for transactions.
gender	integer	Yes	Gender (0 for Male, 1 for Female).
dob	string	Yes	Date of birth in DD/MM/YYYY format.
address	string	Yes	The user's address (max 100 characters).
nationalIdentityNo	string	No	A user's 11-digit NIN. Either this or bvn is required.
ninUserId	string	No	The NIN User ID. Required if nationalIdentityNo is provided.
bvn	string	No	An 11-digit BVN. Either this or nationalIdentityNo is required.
idFront	file	No	Image file for the front of the ID card.
idBack	file	No	Image file for the back of the ID card.
proofAddress	file	No	Image file for proof of address.
profilePicture	file	No	A user's profile picture.
customerImage	string	No	A Base64 string of the customer's image.
customerSignature	string	No	A Base64 string of the customer's signature.

Example cURL Request

curl --location --request POST 'https://your-domain.com/path/to/account_management.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'action=register_account' \
--data-urlencode 'csrf_token=YOUR_CSRF_TOKEN' \
--data-urlencode 'token_verification=YOUR_FINTECH_TOKEN' \
--data-urlencode 'firstName=John' \
--data-urlencode 'lastName=Doe' \
--data-urlencode 'phoneNo=08012345678' \
--data-urlencode 'username=johndoe' \
--data-urlencode 'email=john.doe@example.com' \
--data-urlencode 'pass=SecurePass123' \
--data-urlencode 'pin=1234' \
--data-urlencode 'gender=0' \
--data-urlencode 'dob=25/12/1990' \
--data-urlencode 'address=123 Main Street' \
--data-urlencode 'bvn=12345678901'

Note: For file uploads, use multipart/form-data as the Content-Type.

Response Format

• Success: A JSON object indicating a successful registration.

  {
      "status": "success",
      "message": "Account registered successfully."
  }

• Error: A JSON object with status: "error" and a descriptive message explaining the reason for failure.

  {
      "status": "error",
      "message": "Invalid Fintech Verification Token."
  }

---

3. Authentication & Security