금융보안원 로고

회원가입 로그인

API가이드

인수채권 업권 정보제공 API 규격

  • API 목록 조회 (공통) v1 2021-10-18

    기본 정보
    API ID 정보제공-공통-001 (인수) HTTP Method GET
    API 제공자 공통 API 요청자 마이데이터사업자, 종합포털
    API 명 (URI) /bond/apis
    설명 정보제공자가 제공하는 정보제공 API 목록(정보제공-공통-001, 정보제공-공통-002 포함)을 회신
    - 인증 API는 모든 정보제공자(또는 중계기관)가 공통적으로 구축해야 하므로, 목록을 조회하는 것이 불필요
    - 지원 API는 종합포털과 주고받는 API이기 때문에 API 요청자인 마이데이터사업자가 목록을 조회하는 것이 불필요
    기준시점 현재 시점
    Content-Type(요청) - Content-Type (응답) application/json; charset=UTF-8
    요청 메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    x-api-type API 유형 N aNS(12) 정기적/비정기적 전송 API 유형- 비정기적 전송일 경우 미설정
    Parameter org_code 기관코드 Y aN(10) - 지원 API로부터 배포
    client_id 클라이언트ID Y aN(50) 종합포털에 마이데이터 서비스 등록 시 발급받은 클라이언트 식별값
    - API 요청자가 “종합포털”인 경우, client_id는 PDS 자격증명의 client_id로 요청
    응답메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    Body rsp_code 세부 응답코드 Y aN(5)
    rsp_msg 세부 응답메시지 Y AH(450)
    version 현재 버전 Y aN(10) API 현재 버전 (업권별 정보제공 API)
    - 참고 : 업권별로 버전이 관리되기 때문에 해당 업권의 정보제공API들의 현재버전(버전정보가 존재하지 않는 정보제공-공통-001 API제외)은 모두 동일하며, 해당 현재버전을 회신
    min_version 호환가능 최소 버전 N aN(10) 마이데이터사업자가 이전 버전 호출 시 응답 가능한 최소 버전
    (예: 최신 버전이 v5, min_version=v2이라고 가정 시, 마이데이터사업자는 v2를 호출해도 정보제공자는 해당 버전의 API를 처리하여 회신- 현재버전이 v1인 경우 미회신
    api_cnt API 개수 Y N(3) 제공 API 개수
    api_list API 목록 Y <object>
    --api_code API 구분 코드 Y AN(4) API 구분 코드
    --api_uri API 명 Y aN(50) URI 계층 구조 중 에 해당하는 정보 (예: /account, /accounts/deposit/basic 등)

  • 전송요구 내역 조회 (공통) v1 2021-10-18

    기본 정보
    API ID 정보제공-공통-002 (인수) HTTP Method GET
    API 제공자 공통 API 요청자 마이데이터사업자
    API 명 (URI) /v1/bond/consents
    설명 정보주체가 특정한 전송요구 내역 조회
    - 시행 초기 전산 용량 등을 감안하여 초기에는 전송 주기(fnd_cycle, add_cycle)를 주1회(“1/w”)로 고정하고, 추후 논의 과정을 거쳐 고객의 선택권을 다양화할 예정
    기준시점 현재 시점
    Content-Type(요청) - Content-Type (응답) application/json; charset=UTF-8
    요청 메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header Authorization 접근토큰 Y aNS(1500) 발급한 접근토큰
    - 접근토큰 유형(Bearer)을 명시
    예) Authorization: Bearer 접근토큰
    x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    x-api-type API 유형 Y aNS(12) 정기적/비정기적 전송 API 유형
    Parameter org_code 기관코드 Y aN(10) 정보제공자 기관코드
    - 지원 API로부터 배포
    응답메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    Body rsp_code 세부 응답코드 Y aN(5)
    rsp_msg 세부 응답메시지 Y AH(450)
    is_scheduled 정기적 전송 여부 Y Boolean 정기적 전송을 요구하는지 여부
    fnd_cycle 전송 주기(기본정보) N aNS(5) 기본정보의 정기적 전송 주기
    - 규격 : 횟수/기준 (기준:월=“m”, 주=“w”, 일=“d”)
    <예시>
    1/w : 주1회
    1/d : 일1회
    - is_scheduled='true'인 경우 회신
    add_cycle 전송 주기(추가정보) N aNS(5) 추가정보의 정기적 전송 주기
    - 규격 : fnd_cycle과 동일
    - is_scheduled='true'인 경우 회신
    end_date 종료시점 Y DATE 전송요구 종료 시점
    - 자산목록 전송요구(1차 통합인증) 시 : 전송요구시점부터 7일째 되는 일자 (예: 2021.12.1. 전송요구 시 종료시점은 +7일인 2021.12.8.)
    - 개별인증 시 또는 자산에 대한 세부 전송요구(2차 통합인증) 시 : 전송요구시점부터 1년째 되는 일자 (예: 2021.12.1. 전송요구 시 종료시점은 +1년인 2022.12.1.) 또는 고객이 선택한 일자
    purpose 목적 Y AH(150) 전송을 요구하는 목적
    period 보유기간 Y DATE 전송을 요구하는 개인신용정보의 보유기간
    - 자산목록 전송요구(1차 통합인증) 시 : 전송요구시점부터 7일째 되는 일자 (예: 2021.12.1. 전송요구 시 보유기간은 +7일인 2021.12.8.)
    - 개별인증 시 또는 자산에 대한 세부 전송요구(2차 통합인증) 시 : '99991231' 고정값
    - '99991231' : '서비스 이용 종료시 또는 삭제요구시 까지'를 의미
    is_consent_trans_memo 적요/거래메모 전송요구 여부 N Boolean 정보주체가 보유한 수신계좌의 거래내역 중 적요/거래메모(trans_memo) 정보에 대해 개인신용정보 전송요구를 했는지 여부
    - 적용업권 : 은행업권, 전자금융업권 (그 외 업권은 미회신)
    - “true”인 경우 :
    - 은행업권 : 은행-004에서 적요 회신
    - 전자금융업권 : 전금-004, 전금-103에서 거래메모 회신
    - “false”인 경우 :
    - 은행업권 : 은행-004에서 적요 미회신
    - 전자금융업권 : 전금-004, 전금-103에서 거래메모 미회신
    is_consent_merchant_name_regno 가맹점명/사업자등록번호 전송요구 여부 N Boolean 가맹점명(merchant_name) 및 사업자등록번호(merchant_regno) 정보에 대해 개인신용정보 전송요구를 했는지 여부
    - 적용업권 : 카드업권, 전자금융업권, 통신업권 (그 외 업권은 미회신)
    - “true”인 경우 :
    - 카드업권 : 카드-005, 카드-008, 선불-004에서 가맹점명 및 사업자등록번호 회신, 카드-009에서 가맹점명 회신
    - 전자금융업권 : 전금-004에서 가맹점명 회신, 전금-103에서 가맹점명 및 사업자등록번호 회신
    - 통신업권 : 통신-004에서 가맹점명 회신
    - “false”인 경우 :
    - 카드업권 : 카드-005, 카드-008, 선불-004에서 가맹점명 및 사업자등록번호 미회신, 카드-009에서 가맹점명 미회신
    - 전자금융업권 : 전금-004에서 가맹점명 미회신, 전금-103에서 가맹점명 및 사업자등록번호 미회신
    - 통신업권 : 통신-004에서 가맹점명 미회신
    is_consent_trans_category 상품(구매)분류 전송요구 여부 N Boolean 정보주체의 결제내역 중 상품(구매)분류(코드)(trans_category) 정보에 대해 개인신용정보 전송요구를 했는지 여부
    - 적용업권 : 전자금융업권 (그 외 업권은 미회신)
    - “true”인 경우 :
    - 전자금융업권 : 전금-004, 전금-103에서 상품(구매)분류 (코드) 회신
    - “false”인 경우 :
    - 전자금융업권 : 전금-004, 전금-103에서 상품(구매)분류 (코드) 미회신

  • 인수채권 목록 조회 v1 2021-10-18

    기본 정보
    API ID 채권-001 (인수) HTTP Method GET
    API 제공자 인수채권업권 API 요청자 마이데이터사업자
    API 명 (URI) /v1/bond/bonds
    설명 정보주체가 가입한 인수채권 목록 조회
    기준시점 현재 시점
    Content-Type(요청) - Content-Type (응답) application/json; charset=UTF-8
    요청 메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header Authorization 접근토큰 Y aNS(1500) 발급한 접근토큰
    - 접근토큰 유형(Bearer)을 명시
    예) Authorization: Bearer 접근토큰
    x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    x-api-type API 유형 Y aNS(12) 정기적/비정기적 전송 API 유형
    Parameter org_code 기관코드 Y aN(10) - 지원 API로부터 배포
    search_timestamp 조회 타임스탬프 N N(14) 가장 최근 조회한 시간 (이전 API 호출 시 정보제공자가 회신한 값을 저장하고 있다가 다음 API 호출 시 그 값을 그대로 세팅하여 전송, 최초 API 호출시에는 0으로 세팅)
    - 2.1-[2] 참조
    - next_page가 세팅된 경우 요청에서 제외
    next_page 다음 페이지 기준개체 N aNS(1000) 다음 페이지 요청을 위한 기준개체 (설정 시 해당 개체 후 limit 개 반환)
    처음 API 호출 시에는 해당 정보를 세팅하지 않으며, 다음 페이지 요청 시 직전 조회의 응답에서 얻은 기준개체를 그대로 세팅
    - 2.1-[2] 페이지네이션 참조
    limit 최대조회갯수 Y N(3) 기준개체 이후 반환될 개체의 개수
    - 최대 500까지 설정 가능
    - 2.1-[2] 페이지네이션 참조
    응답메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    Body rsp_code 세부 응답코드 Y aN(5)
    rsp_msg 세부 응답메시지 Y AH(450)
    search_timestamp 조회 타임스탬프 N N(14) API 처리 시점의 현재시각을 설정하여 회신. 다만 정보제공자는 Timestamp 로직을 의무적으로 구현할 필요가 없으며(선택사항), Timestamp 로직 미제공 시에는 항상 0을 회신 또는 미회신
    - 2.1-[2] 참조
    next_page 다음 페이지 기준개체 N aNS(1000) 다음 페이지 요청을 위한 기준개체
    - 다음 페이지 존재하지 않는 경우(마지막 페이지), 미회신
    - 2.1-[2] 페이지네이션 참조
    bond_cnt 채권수 Y N(3)
    bond_list 권면목록 Y Object
    --bond_num 채권번호 Y AH(116) 정보제공자가 부여한 계약의 고유 식별자로써 채권번호, 매입사관리번호(대부업권) 또는 차주번호(한국자산관리공사) 등에 해당
    - 비고) 한국자산관리공사의 차주번호 : 한글(최대50글자)/숫자/특수문자 포함 최대 116바이트
    --is_consent 전송요구 여부 Y Boolean 정보주체가 해당 자산(채권번호)에 대해 개인신용정보 전송요구를 했는지 여부
    --bond_type 기관분류(코드) Y aN(2) 해당 채권(금융상품)을 보유한 기관의 분류
    - <코드표>
    01 : 인수채권 (인수채권 업권)
    02 : 금전대부 (대부 업권)
    03 : 매입추심 (대부 업권)
    --takeover_date 채권인수일/특수채권편입일/최초대출일 Y DATE 채권 인수(매입)를 완료한 일자(인수채권, 매입추심), 특수채권으로 편입된 일자(계약일)(일반금융), 또는 최초 대출일(금전대부)
    - 인수가 여러번 발생한 경우, 마지막 인수한 일자 의미
    - 채권의 양도가 없는 경우 특수채권편입일/최초대출일 회신
    --init_org_code 최초대출기관 N AH(60) 최초의 대출이 실행된 기관
    - 텍스트로 전송
    - 특정 기관이 정보제공자이며 최초 대출기관인 경우 해당 기관명 그대로 입력
    - 기관구분(코드)(bond_type)가 인수채권(‘01’), 매입추심(‘03’)인 경우 최초 대출기관 미회신

  • 인수채권 잔액정보 조회 v1 2021-10-18

    기본 정보
    API ID 채권-002 (인수) HTTP Method POST
    API 제공자 인수채권업권 API 요청자 마이데이터사업자
    API 명 (URI) /v1/bond/bonds/detail
    설명 해당 인수채권 잔액정보 조회
    기준시점 현재 시점
    Content-Type(요청) application/json; charset=UTF-8 Content-Type (응답) application/json; charset=UTF-8
    요청 메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header Authorization 접근토큰 Y aNS(1500) 발급한 접근토큰
    - 접근토큰 유형(Bearer)을 명시
    예) Authorization: Bearer 접근토큰
    x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    x-api-type API 유형 Y aNS(12) 정기적/비정기적 전송 API 유형
    Body org_code 기관코드 Y aN(10) - 지원 API로부터 배포
    bond_num 채권번호 Y AH(116) 정보제공자가 부여한 계약의 고유 식별자
    search_timestamp 조회 타임스탬프 Y N(14) 가장 최근 조회한 시간 (이전 API 호출 시 정보제공자가 회신한 값을 저장하고 있다가 다음 API 호출 시 그 값을 그대로 세팅하여 전송, 최초 API 호출시에는 0으로 세팅)
    - 2.1-[2] 참조
    응답메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    Body rsp_code 세부 응답코드 Y aN(5)
    rsp_msg 세부 응답메시지 Y AH(450)
    search_timestamp 조회 타임스탬프 N N(14) API 처리 시점의 현재시각을 설정하여 회신. 다만 정보제공자는 Timestamp 로직을 의무적으로 구현할 필요가 없으며(선택사항), Timestamp 로직 미제공 시에는 항상 0을 회신 또는 미회신
    - 2.1-[2] 참조
    prev_org_code 직전 채권인계기관 N AH(60) 채권을 인계한 대상기관(채권을 매각한 기관)
    - 텍스트로 전송
    - 장기소액연체채권, 기초수급채권의 경우(흩어진 채권을 일괄적으로 사오는 경우가 존재(계좌가 묶임)) 전송 제외
    - 인계가 여러번 발생한 경우, 마지막 인계 대상 기관을 의미(직전매각사)
    - 직전 채권인계기관 개념이 있는 경우에는 필수 제공(채권-001의 기관구분코드(bond_type)가 인수채권(‘01’) 또는 매입추심(‘03’)인 경우)
    is_debt_mgmt 채무조정 여부 Y Boolean 화해/회생/회복/판결 등 대출정보와 실제와 상이한 경우 총괄
    repay_method 상환방식 (코드) N aN(2) 해당 대출의 상환방식 구분 코드
    - [첨부4] 상환방식 코드
    - 금전대부이며 채무조정 여부가 “false”인 경우 필수 회신
    balance_amt 대출잔액 Y N(15) 잔존 대출잔액 정보(대부업권의 경우 잔존원금(감면전))
    - 이자를 제외한 대출원금 중 고객이 실제 상환해야 할 금액
    - 채무조정시 감면 이후 잔존 대출잔액금을 회신하며, 실제 대출잔액금과 상이할 수 있음
    - 단, 대부업권(매입추심/금전대부)은 감면 이전 금액 전송(매입채권의 경우 매입시 금액)
    bond_principal 대출원금 Y N(15) 해당 대출계약의 원금 전부/매입사의 경우 매입시 잔존원금
    - 한국자산관리공사 상품의 대출원금은 인수채권액을 의미하며 가지급금 포함 가능

  • 인수채권 거래내역 조회 v1 2021-10-18

    기본 정보
    API ID 채권-003 (인수) HTTP Method POST
    API 제공자 인수채권업권 API 요청자 마이데이터사업자
    API 명 (URI) /v1/bond/bonds/transactions
    설명 조회 기간 동안 발생한 정보주체의 인수채권 거래내역 조회 (Pagination, 거래일시 기준 내림차순)
    - 신용정보법 시행령 제28조의3제4항에 의거, 최근 5년 이내 정보 제공
    기준시점 FROM과 TO를 확인하여 해당 기간의 정보를 회신
    Content-Type(요청) application/json; charset=UTF-8 Content-Type (응답) application/json; charset=UTF-8
    요청 메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header Authorization 접근토큰 Y aNS(1500) 발급한 접근토큰
    - 접근토큰 유형(Bearer)을 명시
    예) Authorization: Bearer 접근토큰
    x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    x-api-type API 유형 Y aNS(12) 정기적/비정기적 전송 API 유형
    Body org_code 기관코드 Y aN(10) - 지원 API로부터 배포
    bond_num 채권번호 Y AH(116) 정보제공자가 부여한 계약의 고유 식별자
    from_date 시작일자 Y DATE 조회 시작일자
    to_date 종료일자 Y DATE 조회 종료일자
    next_page 다음 페이지 기준개체 N aN(1000) 다음 페이지 요청을 위한 기준개체 (설정 시 해당 개체 후 limit 개 반환)
    처음 API 호출 시에는 해당 정보를 세팅하지 않으며, 다음 페이지 요청 시 직전 조회의 응답에서 얻은 기준개체를 그대로 세팅
    - 2.1-[2] 페이지네이션 참조
    limit 최대조회갯수 Y N(3) 기준개체 이후 반환될 개체의 개수
    - 최대 500까지 설정 가능
    - 2.1-[2] 페이지네이션 참조
    응답메세지 명세
    HTTP 항목명 항목설명 필수 타입(길이) 설명(비고)
    Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호
    Body rsp_code 세부 응답코드 Y aN(5)
    rsp_msg 세부 응답메시지 Y AH(450)
    next_page 다음 페이지 기준개체 N aNS(1000) 다음 페이지 요청을 위한 기준개체
    - 다음 페이지 존재하지 않는 경우(마지막 페이지), 미회신
    - 2.1-[2] 페이지네이션 참조
    trans_cnt 거래내역수 Y N(3)
    trans_list 거래내역목록 Y Object
    --trans_dtime 거래일시 또는 거래일자 Y DTIME 또는 DATE 해당 채권번호에서 거래가 일어난 일시(YYYYMMDDhhmmss)
    - 시각 정보가 없는 경우 거래일자인 YYYYMMDD 회신 (일부 기관의 경우 거래일자+거래번호로 관리)
    --trans_no 거래번호 N aN(64) 해당 일자의 결제 특정 번호
    (없을 경우 미회신)
    - trans_dtime이 거래일자로 전송될 경우, 해당 일자 내 거래 순서를 확인하기 위해 정보제공자가 임의로 설정한 값
    --trans_amt 거래금액 Y N(15) 해당 채권번호에서 일어난 해당 거래(상환)의 금액
    - 원금과 이자, 수수료 및 기타비용이 포함된 금액
    --balance_amt 거래 후 대출잔액 N N(15) 해당 채권번호에서 거래가 일어난 후 남은 잔여 대출 금액
    - 화해, 개인회생(회생인가금액) 등의 채무조정이 발생한 경우 최종 대출잔액이 남아있으나 종결 가능
    - 대부업권(매입추심/금전대부)은 채무조정 등으로 데이터 변경이 잦아 실시간 반영이 어려운 경우 미회신
    --int_amt 거래금액 중 이자 N F(18,3) 해당 거래의 금액 중 이자금액
    --principal_amt 거래금액 중 원금 N F(18,3) 해당 거래의 금액 중 원금

Table of contents

인수채권 업권 정보제공 API 규격