Skip to main content

KYC Document Upload Workflow

Overview​

This workflow covers the complete KYC (Know Your Customer) document upload process in the GafaPay system. It provides users with the ability to view available KYC document categories, select appropriate document types, and upload required documents for verification purposes.

The workflow consists of several key components that work together to provide a comprehensive document upload experience:

1. Dynamic Category Discovery​

Users can view available document categories based on their user type and document type (KYC, Registration, Business).

2. Document Type Selection​

Users can see specific document types available for each category and understand requirements.

3. Document Upload Process​

Users can upload documents with proper validation and categorization.

4. Document Management​

Users can view, update, and manage their uploaded documents.

Workflow Steps​

1. Get Dynamic Categories​

Purpose: Retrieve available document categories for the user's type and document type (KYC).

Steps:

  1. Call the Get All Dynamic Categories API
  2. Pass the user's type and document type (1=KYC) as parameters
  3. Display available categories with their details
  4. Show category names, keys, and requirements

2. Get Document Types​

Purpose: Retrieve specific document types available for each category.

Steps:

  1. Call the Get All Document Types API
  2. Pass the dynamic category key and document category (1=KYC) as parameters
  3. Display available document types for each category
  4. Show document type titles, requirements, and validation rules

3. Display Document Requirements​

Purpose: Present document requirements and validation rules to the user.

Steps:

  1. Show document type titles and descriptions
  2. Display side type requirements (Front, Back, Both, Document)
  3. Show mandatory status and extra field requirements
  4. Display expiry date requirements if applicable
  5. Show business type restrictions if any

4. Document Upload Process​

Purpose: Upload documents with proper categorization and validation.

Steps:

  1. For each required document type, call the Save User Document API
  2. Pass the document type ID from the previous API response
  3. Include document file information and metadata
  4. Handle multiple document sides if required (Front/Back)
  5. Process extra field validation if applicable

5. Document Verification​

Purpose: Track document upload status and verification progress.

Steps:

  1. Call the Get All User Documents API
  2. Display uploaded documents with their status
  3. Show verification progress and any pending requirements
  4. Allow users to view uploaded document details

API References​

Get All Dynamic Categories​

  • API: Get All Dynamic Categories
  • Endpoint: GET /gafapay/v3/user/dynamic_category
  • Purpose: Retrieve available document categories for user type and document type

Required Parameters:

  • type: Document type (1=KYC, 2=Registration, 3=Business)
  • user_type: Type of user (2=Customer, 3=Merchant, 5=Agent)

Optional Parameters:

  • skip: Pagination offset (default: 0)
  • limit: Number of records to return (default: 10)
  • search_keyword: Search filter for categories

Example Request:

GET /gafapay/v3/user/dynamic_category?type=1&user_type=2&skip=0&limit=10

Response Fields:

  • id: Category unique identifier
  • name: Category display name
  • category_key: Unique category key
  • display_order: Order for display
  • type: Category type (1=KYC, 2=Registration, 3=Business)
  • is_default: Whether this is a default category
  • no_of_doc_required: Number of documents required
  • user_type: Type of user this category applies to

Get All Document Types​

  • API: Get All Document Types
  • Endpoint: GET /gafapay/v3/user/document_type
  • Purpose: Retrieve specific document types for a category

Required Parameters:

  • document_category: Document category (1=KYC, 2=Business)
  • dynamic_category_key: Category key from dynamic categories API

Optional Parameters:

  • user_type: Type of user (2=Customer, 3=Merchant, 5=Agent)
  • document_type: Document type (1=Document, 2=Selfie)
  • expiry_date_required: Filter for documents requiring expiry date
  • skip: Pagination offset (default: 0)
  • limit: Number of records to return (default: 10)

Example Request:

GET /gafapay/v3/user/document_type?document_category=1&dynamic_category_key=KYC&user_type=2

Response Fields:

  • id: Document type unique identifier
  • document_type_title: Display name of the document type
  • document_user_type: Type of user this document applies to
  • document_side_type: Document side type (1=Front, 2=Back, 3=Both, 4=Document)
  • is_mandatory: Whether this document is mandatory
  • document_extra_fields: Additional validation fields required
  • document_type: Document type classification (1=Document, 2=Selfie)
  • document_category: Document category (1=KYC, 2=Business)
  • dynamic_category_key: Key linking to dynamic category
  • expiry_date_required: Whether expiry date is required

Save User Document​

  • API: Save User Document
  • Endpoint: POST /gafapay/v3/user/user_document
  • Purpose: Upload and save user documents with proper categorization

Required Parameters:

  • user_id: ID of the user uploading the document
  • document_type_id: ID of the document type (from document types API)
  • document_path: Array of document file information
  • document_user_type: Type of user uploading the document

Optional Parameters:

  • document_extra_fields_values: Values for extra validation fields
  • expiry_date: Document expiry date (if required)

Example Request:

POST /gafapay/v3/user/user_document
Content-Type: application/json

{
    "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
    "document_type_id": "761b7d7b2b5d49e29de4ad559838d1dc",
    "document_user_type": 2,
    "document_path": [
        {
            "value": "https://s3.ap-south-1.amazonaws.com/bucket/path/document.jpg",
            "type": 1,
            "file_type_extension": "image/jpeg"
        }
    ],
    "expiry_date": 1755925484
}

Get All User Documents​

  • API: Get All User Documents
  • Endpoint: GET /gafapay/v3/user/user_document
  • Purpose: Retrieve user's uploaded documents and their status

Required Parameters:

  • user_id: ID of the user whose documents to retrieve

Optional Parameters:

  • skip: Pagination offset (default: 0)
  • limit: Number of records to return (default: 10)
  • sorting: Sorting criteria for results

Example Request:

GET /gafapay/v3/user/user_document?user_id=fb8f09210e0f46b7b4262d77f5b6c273&skip=0&limit=10

Flow Logic​

1. Initial Category Discovery​

  • Start with the logged-in user's ID and user type
  • Set document type to 1 (KYC) for verification documents
  • Call Get All Dynamic Categories API with user type and document type
  • Display available categories with their names and requirements
  • Show category keys for further API calls

2. Document Type Retrieval​

  • For each category, extract the category_key value
  • Call Get All Document Types API with category key and document category (1=KYC)
  • Filter by user type if needed for user-specific document types
  • Display available document types for each category
  • Show document requirements and validation rules

3. Document Requirements Display​

  • Present document type titles and descriptions to the user
  • Show side type requirements (Front, Back, Both, Document)
  • Display mandatory status and extra field requirements
  • Show expiry date requirements if applicable
  • Display business type restrictions if any
  • Group documents by category for better organization

4. Document Upload Process​

  • For each required document type, collect document files from user
  • Prepare document path array with file URLs and metadata
  • Include extra field values if required by the document type
  • Set expiry date if required by the document type
  • Call Save User Document API with document type ID and file information
  • Handle multiple document sides if required (Front/Back)
  • Process validation errors and retry if necessary

5. Document Status Tracking​

  • Call Get All User Documents API to retrieve uploaded documents
  • Display document status and verification progress
  • Show any pending requirements or validation errors
  • Allow users to view uploaded document details
  • Provide options to update or replace documents if needed

6. Error Handling​

  • Validate API responses for success status
  • Handle document upload failures and retry mechanisms
  • Manage validation errors for extra fields
  • Process file type and size validation errors
  • Display appropriate error messages to users
  • Handle network connectivity issues during upload

7. User Experience Flow​

  • Provide clear navigation between categories and document types
  • Show loading states during API calls and file uploads
  • Display progress indicators for multi-document uploads
  • Maintain consistent pagination across document lists
  • Ensure responsive design for different screen sizes
  • Provide clear feedback for successful uploads and errors

8. Document Management​

  • Allow users to view uploaded documents
  • Provide options to update document information
  • Enable document replacement for rejected documents
  • Show verification status and pending requirements
  • Display document expiry dates and renewal reminders
  • Maintain audit trail of document changes

Constants Reference​

Document Type Constants​

  • KYC = 1: Know Your Customer verification documents
  • Registration = 2: User registration process documents
  • Business = 3: Business verification documents

User Type Constants​

  • Customer = 2: Regular customer users
  • Merchant = 3: Merchant/business users
  • Agent = 5: Agent/representative users

Document Side Type Constants​

  • Front = 1: Front side of document
  • Back = 2: Back side of document
  • Both = 3: Both sides required
  • Document = 4: Single document (no side distinction)

Document Type Classification​

  • Document = 1: Regular document uploads (passport, ID, etc.)
  • Selfie = 2: Selfie/photo verification

Document Status Constants​

  • PENDING = 1: Document is uploaded and awaiting verification
  • VERIFIED = 2: Document has been verified and approved
  • EXPIRED = 3: Document has expired
  • REJECTED = 4: Document was rejected during verification