단계별 메시지 상세 명세

VP 제출 흐름에 따라 사용되는 M310, M320, M400, M900 메시지의 구성과 예시를 설명합니다.

1. VP 준비 단계 (300)

[M310] 프로필 요청 메시지

신분증 앱은 VP 요청(M200)을 받은 뒤 프로필이 필요한 경우 아래 메시지를 만들어 profile 서버로 전송해요.

{
  "type": "mip",
  "version": "1.0.0",
  "cmd": "310",
  "trxcode": "20211102162732145432176790",
  "request": "profile"
}

• request: "profile"로 고정해야 해요.

요청은 base64 인코딩해서 POST /mip/profile 경로로 보내요.

정상 응답 예시

{
  "result": true,
  "data": "base64 인코딩된 프로파일 응답 메시지"
}

오류 응답 예시

{
  "result": false,
  "data": "base64 인코딩된 오류 메시지"
}

오류 메시지를 디코딩하면 다음과 같은 구조예요

{
  "type": "mip",
  "version": "1.0.0",
  "cmd": "900",
  "trxcode": "20211102162732145432176790",
  "errcode": "10002",
  "errmsg": "missing mandatory item: request"
}

자주 발생하는 오류 코드

| 코드 | 설명 | ||| | 10001 | JSON 형식이 아님 | | 10002 | 필수 항목 누락 | | 10100 | request 값이 잘못됨 | | 10104 | 존재하지 않는 trxcode 사용 | | 99999 | 알 수 없는 오류 |

[M320] 이미지 요청 메시지

신분증 앱은 M200 메시지를 참고해서 프로필 이미지가 필요한 경우 아래 메시지를 POST /mip/image로 보내요.

{
  "type": "mip",
  "version": "1.0.0",
  "cmd": "320",
  "trxcode": "20211102162732145432176790",
  "request": "image"
}

정상 응답과 오류 응답 구조는 프로필 요청과 동일해요.

2. VP 제출 단계 (400)

[M400] VP 제출 메시지

VP는 다음 우선순위에 따라 지정된 URL로 제출해요

1. 프로필에 있는 profile.callBackUrl
2. M200 메시지에 있는 호스트의 /mip/vp 경로

제출 메시지 예시

{
  "type": "mip",
  "version": "1.0.0",
  "cmd": "400",
  "request": "presentation",
  "trxcode": "20211102162732145432176790",
  "vp": {
    "presentType": 1,
    "encryptType": 2,
    "keyType": 3,
    "authType": ["pin", "face"],
    "did": "did:kr:mobileid:22siaYR7NxaDQR6HvE318kSu4xfP",
    "nonce": "2704b5e4eb5de74c3ff7956c53ae1dc9596a89545fe581755bee82995f7a83a2",
    "type": "VERIFY",
    "data": "01005666dd8098f6f825...c2b7"
  }
}

• vp.data: base64나 16진수(hex string)로 인코딩된 암호화 VP예요.

응답 예시

// 정상
{
  "result": true
}

// 오류
{
  "result": false,
  "data": "base64 인코딩된 오류 메시지"
}

VP 내부 uncommitted 필드 예시

VP를 복호화하면 vp.data에 uncommitted라는 필드가 포함될 수 있어요. 이 값은 검증기관에서만 사용해요.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "type": [
    "VerifiablePresentation"
  ],
  "uncommitted": {
    "caInfo": {
      "packageName": "com.example.mypackage",
      "faceType": "OTHERS",
      "faceAccessToken": "...",
      "walletId": "...",
      "walletAuthNo": "...",
      "caAppId": "...",
      "vpId": "A01DA4A0-1E10-42F4-A6A2-892637F199FB",
      "attestationCert": "..."
    },
    "signUncommitted": "..."
  }
}

이 값은 사용자 정보 보호를 위해 인증을 수행한 기관이 내부에서만 사용하며, 검증 목적에는 포함되지 않아요.

3. 기타 메시지 (900)

[M900] 오류 메시지

오류 메시지는 다음 두 가지 경우에 사용해요

1. verifier가 신분증 앱에 오류를 알릴 때
2. 신분증 앱이 verifier에 오류를 알릴 때

메시지 구조

{
  "type": "mip",
  "version": "1.0.0",
  "cmd": "900",
  "trxcode": "20211102162732145432176790",
  "errcode": 10002,
  "errmsg": "missing mandatory item: request"
}

verifier → 신분증 앱

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "result": false,
  "data": "base64 인코딩된 오류 메시지"
}

신분증 앱 → verifier

POST /mip/error HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8

{
  "data": "base64 인코딩된 오류 메시지"
}

응답 예시:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "result": true
}