跳轉到

提交用户實名認證資料 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)

1
2
3
4
{
  "code":"PA044",
  "message":"Account not found."
}