2FA 인증

2FA 상품에서 사용하는 API를 한 페이지에서 확인할 수 있습니다.
서비스명 관리, 인증번호 요청/검증, 결과조회까지 순서대로 제공합니다.

서비스명 관리 API는 인증번호 발송 메시지에 서비스명을 표시할 때 사용합니다.

서비스명 등록 서비스명 조회 서비스명 삭제 인증번호 요청 검증 결과조회

서비스명 등록

POST/api/verify/v1/2fa/service/regist

메시지 발송 체험하기 샌드박스로 테스트하기

인증번호 메시지에 노출할 서비스명을 등록합니다. 서비스명은 최대 20바이트(한글 2바이트, 영문/숫자/공백 1바이트)입니다.

Body Parameters

{}JSON

serviceName

필수 String

서비스명입니다.

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/service/regist" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "비즈고",
    "userRef": "verify-service-regist-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "serviceName": "비즈고",
    "userRef": "verify-service-regist-001"
  }
}

서비스명 조회

POST/api/verify/v1/2fa/service

메시지 발송 체험하기 샌드박스로 테스트하기

현재 등록된 서비스명을 조회합니다. 등록된 서비스명이 없으면 빈 문자열이 반환됩니다.

Body Parameters

{}JSON

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/service" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "userRef": "verify-service-list-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "serviceName": "비즈고",
    "regDate": "2026-03-31 10: 39: 11",
    "userRef": "verify-service-list-001"
  }
}

서비스명 삭제

POST/api/verify/v1/2fa/service/delete

메시지 발송 체험하기 샌드박스로 테스트하기

등록된 서비스명을 삭제합니다. 이후 인증문자에는 서비스명이 포함되지 않습니다.

Body Parameters

{}JSON

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/service/delete" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "userRef": "verify-service-delete-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "userRef": "verify-service-delete-001"
  }
}

인증번호 요청

POST/api/verify/v1/2fa/request

메시지 발송 체험하기 샌드박스로 테스트하기

인증번호를 요청합니다. 인증번호는 6자리 숫자이며 유효시간은 3분입니다. 3분 동안 최대 5회 요청할 수 있습니다.

Body Parameters

{}JSON

필수 String

수신번호입니다.

authNumber

String

고정 인증코드가 필요한 경우 지정하는 static OTP입니다.

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

requestId

String

검증 요청에 사용하는 requestId입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/request" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "01000000000",
    "userRef": "verify-request-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "X-Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba1",
    "userRef": "verify-request-001"
  }
}

검증

POST/api/verify/v1/2fa/verify

메시지 발송 체험하기 샌드박스로 테스트하기

사용자가 수신한 인증번호를 검증합니다.

Body Parameters

{}JSON

authNumber

필수 String

인증번호입니다.

필수 String

수신번호입니다.

requestId

String

인증번호 요청 응답에서 받은 검증키입니다.

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/verify" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "authNumber": "123456",
    "to": "01000000000",
    "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba1",
    "userRef": "verify-check-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "X-Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba1",
    "userRef": "verify-check-001"
  }
}

결과조회

POST/api/verify/v1/2fa/logs

메시지 발송 체험하기 샌드박스로 테스트하기

요청일자 기준으로 2FA 결과 이력을 조회합니다.

Body Parameters

{}JSON

requestDate

필수 String

인증번호 요청일자입니다.

requestId

String

검증키입니다.

userRef

String

고객 커스텀 참조값입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

2FA 응답 데이터입니다.

list

Array

결과 목록입니다.

status

String

인증 상태입니다.

verifyDate

String

검증 성공 일시입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/verify/v1/2fa/logs" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "requestDate": "20260331",
    "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba1",
    "userRef": "verify-logs-001"
  }'

응답 예시

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "X-Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "resultMsg": "성공",
    "userRef": "verify-logs-001",
    "list": [
      {
        "requestDate": "2026-03-31 09: 39: 38",
        "status": "PENDING",
        "verifyDate": "",
        "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba1"
      },
      {
        "requestDate": "2026-03-31 09: 40: 02",
        "status": "SUCCESS",
        "verifyDate": "2026-03-31 09: 41: 10",
        "requestId": "58f5edaf-0fc1-3ac7-8fe0-c4453abf0ba2"
      }
    ]
  }
}