Merchant Onboarding

The merchant onboarding process enables businesses to register, configure their account, and get approved to use the Kulpay ecosystem. Kulpay distinguishes between Informal Merchants (street vendors, taxis) and Formal Merchants (retail stores, utilities) to ensure neither is excluded from the platform.

Merchant Categories

Category	Examples	Channel	Hardware
Informal (Micro-Merchant)	Street vendors ("Mamanengue"), taxis, market stalls	Smartphone app	QR Code sticker (no POS needed)
Formal Merchant	Retail stores, utilities, billers	Digital portal (Hakela)	API integration + optional POS

Participants

Participant	Role	Channel
Informal Merchant	Self-onboards via smartphone app using personal ID	Mobile App
Formal Merchant (Business)	Submits registration and onboarding details	Hakela Portal
Kulpay Collection API	Manages onboarding flow and validates data	—
Back Office Reviewer	Reviews and approves/rejects account applications	Kulpay Backoffice

---

Informal Merchant Onboarding (Micro-Merchant)

Informal merchants are onboarded with minimal friction. They receive Micro-Merchant status using their personal ID, and are immediately issued a QR Code sticker — no expensive POS hardware required.

Process Flow

Step-by-Step

Phase 1: Self-Registration

1. Merchant downloads the Kulpay app
2. Registers using their personal ID (BI or Voter's Card)
3. OCR auto-captures name, DOB, and ID number from the document
4. Selfie liveness check and face match verify the merchant's identity

Phase 2: Instant Activation

5. Merchant confirms extracted details and sets an access PIN
6. Micro-Merchant account is created immediately
7. A QR Code sticker is generated and can be printed — customers scan it to pay
8. Merchant can begin accepting payments right away with standard limits

Phase 3: Progressive Verification

9. As transaction volume grows, the merchant is prompted for additional verification
10. Fingerprint or Facial ID capture at an agent location
11. Biometric is linked to authorize high-value settlements to their personal wallet or bank account

Biometric Capture

Phase	Timing	Method	Purpose
Phase 1	During signup	Facial recognition (selfie) via smartphone	Identity verification
Phase 2	As volume grows	Fingerprint at agent location	Authorize high-value settlements

---

Formal Merchant Onboarding

Formal merchants onboard through the Hakela digital portal, uploading business documents for verification. Once approved, they receive a Biller Code and API-led integration into the Kulpay ecosystem.

Process Flow

Step-by-Step

Phase 1: Registration

1. Business authenticates via Keycloak (OIDC identity provider)
2. The system creates a new account with pending status
3. Business initializes the onboarding process

API Endpoints:

• POST /v1/account/onboarding/initialize — Start onboarding

Phase 2: Submit Details

4. Business submits their information through the Hakela portal:

Business Details

• Legal name and short name
• Country, state/province, city
• Alvará (business license)
• NUIT (tax identification number)
• BR (business registration number)
• VAT number

Bank Details

• NUIB (National Unique Identification of Bank)
• NIB (Bank Identification Number)
• Account number
• Bank name
• Account holder name

Tax Details

• Tax ID (NUIT)
• VAT number

Person of Contact

• First name and last name
• Phone number
• Email address

5. The designated administrator's biometrics (selfie) are captured for corporate governance and high-value internal transfer authorization
6. Business uploads supporting documents (Alvará, tax certificate, registration certificate, etc.)

API Endpoints:

• PUT /v1/account/onboarding/details — Submit/update all details
• POST /v1/files — Upload supporting documents
• GET /v1/account/onboarding/details — Review submitted details

Phase 3: Submit for Review

7. Business finalizes onboarding submission
8. Account status changes to pending_review
9. The system validates submitted data and flags any issues

API Endpoints:

• POST /v1/account/onboarding/finish — Submit for review
• GET /v1/account/onboarding — Check onboarding status

Phase 4: Review & Approval

10. Back office reviewer evaluates the application
11. Reviewer can:
    • Approve — Account becomes active, a Biller Code is assigned
    • Reject — Account becomes rejected with a reason
    • Request changes — Business is asked to update information

API Endpoints:

• POST /v1/accounts/{account_id}/approve — Approve account
• POST /v1/accounts/{account_id}/reject — Reject account
• POST /v1/accounts/{account_id}/suspend — Suspend account

Phase 5: Operational Setup

12. Once approved, the business receives its Biller Code for API-led integration
13. The business sets up collection methods (SIMO ERV or interbank)
14. The business can now create collection requests and collect payments

API Endpoints:

• POST /v1/collection-methods — Create collection methods
• POST /v1/collection-requests — Start issuing invoices

Biometric Capture (Formal Merchants)

Phase	Timing	Method	Purpose
Phase 1	During onboarding	Designated administrator's selfie	Corporate governance
Ongoing	High-value transfers	Administrator biometric verification	Authorize internal transfers

---

Account Status Lifecycle

Status	Description	Can Accept Payments?
pending	Account created, onboarding in progress	No
pending_review	Onboarding submitted, awaiting approval	No
active	Account approved and fully operational	Yes
rejected	Application rejected (reason provided)	No
suspended	Account temporarily disabled	No

Validation Errors

During the review process, the system may flag validation errors:

{
  "errors": [
    {
      "field": "bank_details.nib",
      "message": "Invalid NIB format - must be 21 digits",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "tax_details.vat_number",
      "message": "VAT number does not match tax authority records",
      "code": "VALIDATION_FAILED"
    }
  ]
}

Required Documents

Informal Merchants

Document	Description	Required
Personal ID (BI or Voter's Card)	Identity document	Yes

Formal Merchants

Document	Description	Required
Alvará (Business License)	Official business license	Yes
Business Registration (BR)	Company registration certificate	Yes
Tax Certificate (NUIT)	Tax identification document	Yes
Bank Account Statement	Proof of bank account ownership	Yes
VAT Registration	Value-Added Tax registration	Conditional
Power of Attorney	If submitted by a representative	Conditional

Related API Endpoints

Endpoint	Purpose
GET /v1/account	Get current account information
GET /v1/account/onboarding	Check onboarding status
GET /v1/account/onboarding/details	Review submitted details
PUT /v1/account/onboarding/details	Submit/update details
POST /v1/account/onboarding/initialize	Start onboarding
POST /v1/account/onboarding/finish	Submit for review
POST /v1/files	Upload documents
POST /v1/accounts/{id}/approve	Approve account
POST /v1/accounts/{id}/reject	Reject account

Business Rules

• Informal merchants are onboarded with personal ID only — no business documents required
• Formal merchants require a valid NUIT, Alvará, and BR for Mozambique regulatory compliance
• Bank details must include a valid NIB for receiving payment settlements
• The person of contact must have at least one form of communication (phone or email)
• Rejected accounts can resubmit after correcting the flagged issues
• Suspended accounts retain their data but cannot accept new payments
• Account approval is required before any collection methods can be created
• QR Code stickers are issued immediately to informal merchants upon registration
• Biller Codes are assigned to formal merchants upon approval