KYC

Dokumen ini menjelaskan endpoint terkait KYC submission dan master data KYC (employment, industry, annual income, trade sum, dll.).

Semua response memakai envelope di docs/bitwewe/api-conventions.

API v1 — Submit KYC

Route

• Method: POST
• Path: /api/user/kyc-bind
• Route file: routes/api.php
• Controller: App\Http\Controllers\Api\KycController@bindKyc
• Request validation: App\Http\Requests\Api\BindKycRequest
• Middleware: auth.xtoken, verified:api (grup protected)

Content-Type

BindKycRequest membutuhkan upload file image, imageFront, imageBehind, sehingga request harus dikirim sebagai multipart/form-data.

Payload

Field penting (ringkas dari BindKycRequest::rules()):

Field	Tipe	Wajib	Catatan validasi
idCard	string	Ya	Indonesia: digits_between:15,16; non-ID: alpha_num, max 30
countryId	string/number	Ya
country	string	Ya	Dipakai untuk menentukan aturan Indonesia/non-Indonesia
image	file	Ya	image, mimes:jpeg,png,jpg
imageFront	file	Ya	selfie close mouth
imageBehind	file	Ya	selfie open mouth
address	string	Ya
birthDate	string	Ya	format mengikuti input klien (disimpan ke birth_date)
fullName	string	Ya
occupationId	string/number	Ya
annualIncomeId	string/number	Ya
tradeVolId	string/number	Ya
industryId	string/number	Tidak	nullable
companyName	string	Tidak	nullable
nationality	string/number	Ya
birthPlace	string	Ya
gender	string	Ya	dipakai untuk Dukcapil mapping (male/female)
period	string	Ya
province	string	Ya
city	string	Ya
postalCode	string	Ya
relativeName	string	Ya
relationship	string	Ya
relativePhone	string	Ya
income	number	Ya	exists:App\\Models\\UserIncome,id
reason	number	Ya	exists:App\\Models\\UserReason,id
npwp	string	Tidak	Indonesia: digit 15–20; non-ID: alnum max 30

Proses server (ringkas)

• Menolak jika ada AuthenticationInfo approved dengan id_card yang sama (api.id_card_existed).
• Menolak jika KYC user sudah approved (api.kyc_already_approved) atau masih pending review (api.kyc_waiting_for_review).
• Menghitung risk score dari RiskMultiplier (country, occupation, annual income, trade sum).
• Upload gambar ke OSS (jika gagal: api.oss_upload_fail).
• Menyimpan/menimpa AuthenticationInfo status PENDING1.
• Mengisi sebagian data ke model User (country_id, full_name, id_card, kyc_status).
• Menjalankan proses verifikasi Dukcapil dalam try-catch (error tidak menggagalkan response ke user).

Response sukses (200)

data berasal dari $authenticationInfo->data():

{
  "code": 200,
  "title": "OK",
  "message": "api.kyc_submitted",
  "result": true,
  "data": {
    "...": "..."
  }
}

Response gagal (umum)

Kondisi	HTTP	message
Validasi payload gagal	400	pesan validasi pertama
idCard sudah dipakai KYC approved	400	api.id_card_existed
KYC sudah approved	400	api.kyc_already_approved
KYC sedang direview	400	api.kyc_waiting_for_review
Upload OSS gagal	400	api.oss_upload_fail

---

API v1 — Master data KYC (protected)

Semua endpoint di bawah berada dalam grup auth.xtoken, verified:api.

Method	Path	Controller@method	Catatan
GET	/api/kyc/employments	KycController@getAllEmployment	cache Redis KEY_EMPLOYMENTS_ALL
GET	/api/kyc/annual-incomes	KycController@getAnnualIncomeList	cache Redis KEY_ANNUAL_INCOME_ALL
GET	/api/kyc/trade-sums	KycController@getTradeSumList	cache Redis KEY_TRADE_SUM_ALL
GET	/api/kyc/industry	KycController@getAllIndustry	cache Redis KEY_INDUSTRY_ALL
GET	/api/kyc/reason	KycController@getAllReason	cache Redis KEY_REASON_ALL
GET	/api/kyc/income	KycController@getAllIncome	cache Redis KEY_INCOME_ALL

Response sukses umumnya sendResponse(<list>, null) sehingga field message bisa null.

Untuk detail bentuk item list, lihat method data() pada model terkait (mis. Employment, Industry, AnnualIncome, TradeSum).