Merchant Registration Current Flow

This document summarizes the merchant registration flow currently active in apps/mobile_user and merchant_core_api.

Flow Overview

The current merchant registration flow is split into:

1. Data Usaha
2. Verifikasi Identitas
3. Foto Tempat Usaha
4. Detail Identitas
5. Alamat & Lokasi
6. Rekening Bank
7. Pemilihan Perangkat
8. Ringkasan (non-step, final review before submit)
9. Aktivasi Selesai (info page, not an input step)

UI notes:

• the progress indicator only covers the 7 input steps
• the Ringkasan page is no longer counted as a step
• the Aktivasi Selesai page only informs the user that data has been submitted

Draft and Persistence in the App

The merchant registration draft is stored in the application's secure storage via:

• merchant_registration_draft_service.dart

Principles currently in effect:

• the user can navigate between steps without losing their input
• summary data can be edited back into the related step
• the draft is cleared after the registration submit completes
• exiting to the home screen before submit can reset the flow to default in line with the UX rule applied in the app

Step 1 Data Usaha Detail

The Data Usaha step currently contains:

• Nama Usaha
• Bentuk Usaha
• Jenis Usaha
• Omzet Rata-rata / Bulan
• Jumlah Karyawan
• the Skoring Usaha result used to read the Skala Usaha

Applicable rules:

• Bentuk Usaha must be selected: Perseorangan or Badan Usaha
• Jenis Usaha is sourced from the master db_reference.public.ref_business_type
• Omzet Rata-rata / Bulan is stored as a numeric value
• Jumlah Karyawan is stored as a numeric value
• Skala Usaha is derived from the combination of revenue + employee count
• the final scale follows the higher indicator between the revenue band and the employee-count band

Reference masters used:

• GET /references/business-types
• GET /references/business-scales

Recorded Business Master Data

This list is the reference of business terms currently used in the merchant registration flow and the business profile.

Business Form

• Perorangan
• Perseorangan
• Badan Usaha

Business Scale

• Mikro
• Kecil
• Menengah

Business Category

• Perdagangan
• Industri Pengolahan
• Jasa
• dan lainnya

Sample Business Types

• Toko Pakaian & Aksesoris
• Apotek / Toko Obat
• Toko Kelontong / Sembako
• Minuman Kekinian / Juice / Tea
• Studio Foto / Printing
• Cuci Motor / Mobil

Steps That Touch the User Database

Some data is not only stored in the registration draft but is also persisted to the user profile:

• Detail Identitas
  • full_name
  • nik
  • gender
• Edit Profile / Verifikasi Gmail
  • email
  • email_verified

These fields are stored in:

• identity.users
• identity.user_emails

NIK is currently persisted to the database and is no longer kept locally only.

Submitting the Merchant Registration

When the user taps Aktifkan Toko on the Ringkasan page:

• the app calls POST /merchant/registration
• the backend creates a new row in merchant.merchant_registration_requests
• the initial request status is pending
• the active merchant is not created immediately

Tables involved:

• merchant.merchant_registration_requests

Important fields currently sent:

• core merchant data
• business_entity_type
• business_type_id
• business_type_name
• average_monthly_revenue
• employee_count
• business_scale_code
• business_scale_name
• referral_code
• referral partner snapshot:
  • referral_partner_id
  • referral_partner_code
  • referral_partner_name
• structured address
• merchant contact
• device & service fee consent
• terms-of-service consent
• privacy-policy consent

Currently Stored Legal Consent

Merchant registration consent is currently stored in both the registration request and the active merchant:

• device_fee_service_accepted
• terms_of_service_accepted
• privacy_policy_accepted

Legal document source:

• legal.documents

Currently available documents:

• terms_of_service
• privacy_policy

In mobile, the Ketentuan Layanan and Kebijakan Privasi links on the Ringkasan page can be opened without leaving the registration flow.

Step 7 Pemilihan Perangkat Detail

The Pemilihan Perangkat step currently contains:

• QRIS Plus device option
• shipping address summary
• partner Referral Code (optional)

Applicable rules:

• Referral Code is stored in the merchant registration draft
• if filled, the backend validates the code against the partner.partners master
• only an active partner referral code is linked to the partner
• if the code is empty, the registration is still processed as a Kesles Merchant direct merchant
• if the code does not match, the registration is still processed as a Kesles Merchant direct merchant
• the referral partner snapshot is only stored when an active partner is found

Request and Merchant Status

Statuses currently used in the registration flow:

Registration request

• pending
• pending_review

Active merchant

• draft
• inactive
• active
• suspended
• deleted

Operational meaning:

• pending: the application has been submitted
• pending_review: the application is under internal review
• active: the merchant is active and can use active-merchant features

Status Criteria Reference

This section summarizes the business and operational statuses currently used or used as the implementation reference in the merchant application.

User Status

User status is stored in identity.users.

• active
  • the user is active and can use the app normally
• inactive
  • the user exists in the system but is not yet actively used
• suspended
  • the user is temporarily suspended
• locked
  • the user is locked and requires further action to be usable again
• deleted
  • the user is treated as no longer active in the system

Merchant Status

Active merchant status is stored in merchant.merchants.

• draft
  • the merchant is incomplete or has not entered the operational active stage
• active
  • the merchant is active and can accept payments and use merchant features
• inactive
  • the merchant is recorded but not yet operationally active
• suspended
  • the merchant is temporarily suspended
• deleted
  • the merchant is no longer active in the system

Merchant Registration Request Status

Registration request status is stored in merchant.merchant_registration_requests.

• pending
  • the application has been submitted by the user
• pending_review
  • the application is under internal review
• approved
  • the application is approved as the result of review
• rejected
  • the application is rejected
• cancelled
  • the application is cancelled

Notes:

• in the operational mobile flow, the most-used statuses are pending and pending_review
• after approval, the active merchant data is moved into merchant.merchants

Terminal Device Status

Terminal device status is split into two layers: an operational status for UI and a technical status for the device lifecycle.

Operational terminal device status

• inactive
  • the merchant has not ordered a terminal device from Kesles Merchant, or the device is not yet ready to use
• active
  • the merchant is active and the device has been activated for use
• online
  • the device is currently connected and actively monitoring transactions
• offline
  • the device is not currently connected

Technical terminal device status

• assigned
  • the device is allocated to the merchant but not yet operationally active
• maintenance
  • the device is in repair or inspection
• returned
  • the device has been returned

Rules derived from merchant status:

• if the merchant account is suspended or deleted, the device status in the UI is treated as inactive

Terminal Device Order Status

This is the overall order status for the terminal device.

• draft
  • the order has just been created and is not yet processed
• menunggu_pembayaran
  • the order has been created and is awaiting payment
• menunggu_verifikasi
  • the payment proof has been uploaded and is awaiting verification
• diproses
  • the order is being processed internally
• selesai
  • the order is complete
• dibatalkan
  • the order is cancelled

Notes:

• this pemesanan status is the order-level status
• pembayaran and pengiriman are derived statuses attached to the same order

Payment Status

This describes the payment condition of the terminal device order.

• belum_bayar
  • no payment has been received yet
• menunggu_verifikasi
  • the payment has been sent by the user but is not yet internally verified
• berhasil
  • the payment has been verified
• gagal
  • the payment failed or is invalid
• dibatalkan
  • the payment is cancelled

Shipping Status

This describes the fulfillment and shipping condition of the terminal device.

• belum_diproses
  • the order has not entered the fulfillment stage
• diproses
  • the order is being prepared internally
• siap_dikirim
  • the device is ready to be handed over to logistics
• dikirim
  • the device is in transit
• diterima
  • the device has been received by the merchant
• retur
  • the device is in the return process

Internal Review Process

For internal testing, the following endpoints are currently available:

• POST /internal/merchant/registration/review
• POST /internal/merchant/registration/approve
• POST /internal/merchant/status

Applicable transitions:

• pending -> pending_review
• pending_review -> active
• active -> suspended
• active -> deleted
• suspended -> active
• suspended -> deleted

On approve:

• data is moved from merchant_registration_requests to merchant.merchants
• a new row is created in merchant.merchant_users
• the processed registration request is deleted
• the merchant reviewed_at is set
• the business profile (business form, business type, revenue, employee count, business scale) is also moved into the active merchant
• all consents are also moved into the active merchant

Merchant Fields Exposed in Profile

The GET /auth/profile endpoint currently returns a merchant snapshot used by the mobile UI:

• merchant_id
• merchant_name
• merchant_status
• merchant_contact_phone
• merchant_contact_email
• merchant_address_line
• merchant_province_name
• merchant_city_name
• merchant_district_name
• merchant_subdistrict_name
• merchant_postal_code
• merchant_reviewed_at
• merchant_device_fee_service_accepted
• merchant_terms_of_service_accepted
• merchant_privacy_policy_accepted

These fields are used by:

• page header
• Profil Merchant
• Kontrak & Kewajiban
• merchant state on Home, Laporan, Transaksi, and Perangkat

Documents and Contract on Profile

The Kontrak & Kewajiban menu currently reads merchant status from the profile snapshot and shows:

• merchant contract status
• device & service fee consent status
• terms-of-service consent status
• privacy-policy consent status
• Tanggal Review based on merchant_reviewed_at

Behavior when merchant is inactive:

• contract and device fields show -
• Persetujuan shows -
• Tanggal Review shows -

Behavior when the merchant has registered:

• Persetujuan may show Sudah Dicentang

Behavior when the merchant has been reviewed/active:

• Tanggal Review is taken from the merchant's review date field

Important Files

• merchant_activation_summary_page.dart
• merchant_device_selection_page.dart
• merchant_registration_draft_service.dart
• merchant_api_service.dart
• merchant_handlers.go
• internal_merchant_handlers.go
• merchant/merchant.go
• profile/store.go

Related Migrations

• 011_add_structured_address_to_merchants.sql
• 012_create_merchant_registration_requests.sql
• 013_extend_merchant_registration_request_statuses.sql
• 018_add_registration_consents.sql
• 019_add_reviewed_at_to_merchants.sql
• 020_add_business_profile_to_merchants.sql
• 022_add_partner_referral_to_merchants.sql