提交用户實名認證資料 Acceptance

設計背景與調用時機¶

目的¶

透過事先提交合作方的用戶實名認證資料，可以讓用戶省去自行輸入「基本資訊」及「證件上傳」的步驟，簡化用戶在 Cabital 的實名認證流程。

機制¶

不論下列事件先後順序為何，都會自動觸發用戶同名認證流程（KYC Match），匹配合作方與 Cabital 方的用戶實名認證資料，無需再調用 KYC Match API。

合作方提交用户實名認證資料
用戶完成 Cabital 的實名認證流程

預填機制

當以下條件同時滿足時，才會生效

合作方在用戶尚未訪問 KYC 頁時，就已經有提交用户實名認證資料
用戶首次訪問 KYC 頁面
resident 不為空物件

調用時機¶

當合作方收到 Webhook Callback status 為 INITIALIZED 時，此時合作方可以調用此 API 將用戶的實名認證資料提交給 Cabital。

請注意

一但請求成功後，該用戶的實名認證資料不能變動，後續的請求並不會更新該資料

POST https://connect.cabital.com/api/v1/accounts/{account_id}/kycinfo/submit

用戶帳號狀態條件¶

已綁定
已通過實名認證

請求 Path 參數¶

參數	必填	說明
`account_id`	是	Cabital 提供的帳號 ID

請求 Body 參數¶

類型：multipart/form-data

參數	必填	類型	說明
`metadata`	是	object	用戶實名認證資料，請參閱下方 `metadata` 結構
`files`	否	file	有正反面的證件檔案系統按檔案順序識別正反面：第一個為 `正面`，第二個為 `背面`，其餘檔案將被忽略檔案格式僅限 `jpeg`、`png` 或 `webp`

`metadata` 結構¶

參數	必填	類型	說明
`idDocType`	是	string	證件類型，僅支援以下類型： `ID_CARD`：身分證 `PASSPORT`：護照 `DRIVER_LICENSE`：駕照 `RESIDENCE_PERMIT`：居住證 `OTHER`：其他
`idIssuingCountry`	是	string	發證國家 ISO 3166-1 三位字母代碼
`number`	是	string	證件上的號碼
`dob`	是	string	證件上的出生日期，格式 `YYYY-MM-DD`
`firstName`	是	string	名
`lastName`	是	string	姓
`issuedDate`	否	string	發證日期，格式 `YYYY-MM-DD`
`validUntil`	否	string	發證到期日期，格式 `YYYY-MM-DD`
`middleName`	否	string	中間名
`legalName`	否	string	法定名字
`placeOfBirth`	否	string	出生地
`resident`	否	object	居住地資訊 1. 建議全部填寫，簡化用戶的 KYC 流程 2. 請參閱下方 `resident` 結構
`additionalInfo`	否	object	額外資訊，可以任意填寫

`resident` 結構¶

參數	類型	說明
`postalCode`	string	居住郵遞區號
`country`	string	居住國家 ISO 3166-1 三位字母代碼
`state`	string	居住省
`city`	string	居住城市
`streetLine1`	string	居住地址 1
`streetLine2`	string	居住地址 2

返回參數¶

參數	類型	說明
`Metadata`	object	用戶實名認證資料，請參閱上方 `metadata` 結構

範例¶

請求數據¶

curl -X POST 'https://connect.cabital.com/api/v1/accounts/7d1d96fc-ae29-496c-a474-c37089f1b6c7/kycinfo/submit' \
--form 'metadata="{
    \"idDocType\": \"ID_CARD\",
    \"idIssuingCountry\": \"TWN\",
    \"number\": \"A164163070\",
    \"dob\": \"1987-07-30\",
    \"issuedDate\": \"2022-07-01\",
    \"validUntil\": \"2023-12-31\",
    \"firstName\": \"John\",
    \"middleName\": \"Michael\",
    \"lastName\": \"Doe\",
    \"placeOfBirth\": \"Taipei\",
    \"resident\": {
      \"postalCode\": \"10601\",
      \"country\": \"Taiwan\",
      \"city\": \"Taipei city\",
      \"streetLine1\": \"Street line 1\",
      \"streetLine2\": \"Street line 2\"
    },
    \"additionalInfo\": { \"job\": \"engineer\" }
  }"

返回數據（成功 `201 Created`）¶

{
  "Metadata": {
    "idDocType": "ID_CARD",
    "idIssuingCountry": "TWN",
    "number": "A164163070",
    "dob": "1987-07-30",
    "issuedDate": "2022-07-01",
    "validUntil": "2023-12-31",
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "placeOfBirth": "Taipei",
    "resident": {
      "postalCode": "10601",
      "country": "Taiwan",
      "city": "Taipei city",
      "streetLine1": "Street line 1",
      "streetLine2": "Street line 2"
    },
    "additionalInfo": { "job": "engineer" }
  }
}

返回數據（失敗 `400 Bad Request`）¶

{
  "code":"PA044",
  "message":"Account not found."
}