오픈API
입금이체
"입금이체 API"는 이용기관이 목적지 계좌로 대금을 송금할 수 있도록 합니다.
이용기관은 오픈뱅킹을 통하여 획득한 핀테크이용번호를 사용할 수도 있고, 실계좌번호를 사용하여 API를 호출 할 수도 있습니다.
입금이체 API는 POST 메소드로 호출되며, 상세 스펙 및 호출 예제는 아래와 같습니다.
<입금이체 API - 핀테크이용번호 사용>
요청메시지 URL
| HTTP URL | https://openapi.openbanking.or.kr/v2.0/transfer/deposit/fin_num |
|---|---|
| HTTP Method | POST |
| Content-Type | application/json; charset=UTF-8 |
요청 메시지 명세
| HTTP | 항목 | 값 | 필수 | TYPE (길이) | 설명 |
|---|---|---|---|---|---|
| Header | Authorization | Bearer <access_token> | Y | 오픈뱅킹으로부터 전송받은 Access Token을 HTTP Header에 추가 [ scope = oob ] | |
| Body | cntr_account_type | "N" | Y | A(1) | 약정 계좌/계정구분 |
| cntr_account_num | "1101230000678" | Y | AN(16) | 약정 계좌/계정 번호 | |
| wd_pass_phrase | "790d56ed........6b821a69" | Y | aN(128) | 입금이체용 암호문구주1) | |
| wd_print_content | "환불금액" | Y | AH(20) | 출금계좌인자내역 | |
| name_check_option | "on" or "off" | Y | aN(3) | 수취인성명검증 여부(on:검증함) (미지정 시 기본값: "on") | |
| sub_frnc_name | “하위가맹점” | N | AH(40) | 하위가맹점명 | |
| sub_frnc_num | “123456789012” | N | AN(20) | 하위가맹점번호 | |
| sub_frnc_business_num | “1234567890” | N | N(10) | 하위가맹점 사업자등록번호 | |
| tran_dtime | "20190910101921" | Y | N(14) | 요청일시 | |
| req_cnt | 고정값 : 1 | Y | N(5) | 입금요청건수주2) | |
| req_list | <object> | Y | 입금요청목록 | ||
| --tran_no | "1" | Y | N(5) | 거래순번 | |
| --bank_tran_id | "F123456789U4BC34239Z" | Y | AN(20) | 은행거래고유번호 | |
| --fintech_use_num | "123456789012345678901234" | Y | AN(24) | 핀테크이용번호 | |
| --print_content | "쇼핑몰환불" | Y | AH(20) | 입금계좌인자내역 | |
| --tran_amt | "10000" | Y | N(12) | 거래금액 | |
| --req_client_name | “홍길동” | Y | AH(20) | 요청고객성명 | |
| --req_client_bank_code | "097" | N | AN(3) | 요청고객계좌 개설기관.표준코드 | |
| --req_client_account_num | "1101230000678" | N | AN(16) | 요청고객계좌번호 | |
| --req_client_fintech_use_num | "123456789012345678901234" | N | AN(24) | 요청고객핀테크이용번호 | |
| --req_client_num | “HONGGILDONG1234” | Y | AN(20) | 요청고객회원번호 | |
| --transfer_purpose | “TR” | Y | AN(2) | 이체용도 | |
| --recv_bank_tran_id | "F123456789U4BCT4112Z" | N | AN(20) | 수취조회 은행거래고유번호 | |
| --cms_num | “93848103221” | N | AN(32) | CMS 번호 |
주1) API 포털의 이용기관 환경설정 메뉴에서 설정하며, 담당자가 입력한 암호문구를 해시적용
(SHA-512)하여 생성
주2) 한번의 API 호출로 1건씩 입금 가능
요청 메시지 형태
{
"cntr_account_type": "N",
"cntr_account_num": "00012345678901234",
"wd_pass_phrase": "790d56ed........6b821a69",
"wd_print_content": "환불금액",
"name_check_option": "on",
"sub_frnc_name": “하위가맹점”,
"sub_frnc_num": “123456789012”,
"sub_frnc_business_num": “1234567890”,
"tran_dtime": "20190910101921",
"req_cnt": "1",
"req_list": [
{
"tran_no": "1",
"bank_tran_id": "F123456789U4BC34239Z",
"fintech_use_num": "123456789012345678901234",
"print_content": "쇼핑몰환불",
"tran_amt": "10000",
"req_client_name": “홍길동”,
"req_client_bank_code": "097",
"req_client_account_num": "00012300000678",
"req_client_num": “HONGGILDONG1234”,
"transfer_purpose": “TR”,
“recv_bank_tran_id”: "F123456789U4BCT4112Z",
“cms_num”: “93848103221”
}
]
}
응답 메시지 명세
| HTTP | 항목 | 값 | TYPE (길이) | 설명 |
|---|---|---|---|---|
| Body | api_tran_id | "2ffd133a-d17a-431d-a6a5" | aNS(40) | 거래고유번호(API) |
| api_tran_dtm | "20190910101921567" | N(17) | 거래일시(밀리세컨드) | |
| rsp_code | "A0000" | AN(5) | 응답코드(API) | |
| rsp_message | "" | AH(300) | 응답메시지(API) | |
| wd_bank_code_std | "097" | AN(3) | 출금기관.표준코드 | |
| wd_bank_code_sub | "1230001" | AN(7) | 출금기관.점별코드 | |
| wd_bank_name | "오픈은행" | AH(20) | 출금기관명 | |
| wd_account_num_masked | "000-1230000-***" | NS*(20) | 출금계좌번호(출력용) | |
| wd_print_content | "환불금액" | AH(20) | 출금계좌인자내역 | |
| wd_account_holder_name | "허균" | AH(20) | 송금인성명 | |
| res_cnt | "1" | N(5) | 입금건수 | |
| res_list | <object> | 입금목록 | ||
| --tran_no | "1" | N(5) | 거래순번 | |
| --bank_tran_id | "F123456789U4BC34239Z" | AN(20) | 거래고유번호(참가은행) | |
| --bank_tran_date | "20190910" | N(8) | 거래일자(참가은행) | |
| --bank_code_tran | "097" | AN(3) | 응답코드를 부여한 참가은행.표준코드 | |
| --bank_rsp_code | "000" | AN(3) | 응답코드(참가은행) | |
| --bank_rsp_message | "" | AH(100) | 응답메시지(참가은행) | |
| --fintech_use_num | "123456789012345678901234" | AN(24) | 핀테크이용번호 | |
| --account_alias | "급여계좌" | AH(50) | 계좌별명(Alias) | |
| --bank_code_std | "097" | AN(3) | 입금(개설)기관.표준코드 | |
| --bank_code_sub | "1230001" | AN(7) | 입금(개설)기관.점별코드 | |
| --bank_name | "오픈은행" | AH(20) | 입금(개설)기관명 | |
| --savings_bank_name | “오픈저축은행” | AH(20) | 개별저축은행명 | |
| --account_num_masked | "000-1230000-***" | NS*(20) | 입금계좌번호(출력용) | |
| --print_content | "쇼핑몰환불 | AH(20) | 입금계좌인자내역 | |
| --account_holder_name | "홍길동" | AH(20) | 수취인성명 | |
| --tran_amt | "10000" | N(12) | 거래금액 | |
| --cms_num | “93848103221” | AN(32) | CMS 번호 |
응답 메시지 형태
{
"api_tran_id": "2ffd133a-d17a-431d-a6a5",
"api_tran_dtm": "20190910101921567",
"rsp_code": "A0000",
"rsp_message": "",
"wd_bank_code_std": "097",
"wd_bank_code_sub": "1230001",
"wd_bank_name": "오픈은행",
"wd_account_num_masked": "000-1230000-***",
"wd_print_content": "환불금액",
"wd_account_holder_name": "허균",
"res_cnt": "1",
"res_list": [
{
"tran_no": "1",
"bank_tran_id": "F123456789U4BC34239Z",
"bank_tran_date": "20190910",
"bank_code_tran": "097",
"bank_rsp_code": "000",
"bank_rsp_message": "",
"fintech_use_num": "123456789012345678901234",
"account_alias": "급여계좌",
"bank_code_std": "097",
"bank_code_sub": "1230001",
"bank_name": "오픈은행",
"account_num_masked": "000-1230000-***",
"print_content": "쇼핑몰환불",
"account_holder_name": "홍길동",
"tran_amt": "10000“,
“cms_num”: “93848103221”
}
]
}
<입금이체 API - 계좌번호 사용>
요청메시지 URL
| HTTP URL | https://openapi.openbanking.or.kr/v2.0/transfer/deposit/acnt_num |
|---|---|
| HTTP Method | POST |
| Content-Type | application/json; charset=UTF-8 |
요청메시지 명세
| HTTP | 항목 | 값 | 필수 | TYPE (길이) | 설명 |
|---|---|---|---|---|---|
| Header | Authorization | Bearer <access_token> | Y | 오픈뱅킹으로부터 전송받은 Access Token을 HTTP Header에 추가 [ scope = oob ] | |
| Body | cntr_account_type | "N" | Y | A(1) | 약정 계좌/계정구분 N:계좌, C:계정 |
| cntr_account_num | "1101230000678" | Y | AN(16) | 약정 계좌/계정 번호 | |
| wd_pass_phrase | "790d56ed........821a69" | Y | aN(128) | 입금이체용 암호문구주1) | |
| wd_print_content | "출금계좌인자내역" | Y | AH(20) | 출금계좌인자내역 | |
| name_check_option | "on" or "off" | Y | aN(3) | 수취인성명검증 여부(on:검증함) (미지정 시 기본값: "on") | |
| sub_frnc_name | “하위가맹점” | N | AH(40) | 하위가맹점명 | |
| sub_frnc_num | “123456789012” | N | AN(20) | 하위가맹점번호 | |
| sub_frnc_business_num | “1234567890” | N | N(10) | 하위가맹점 사업자등록번호 | |
| tran_dtime | "20190910101921" | Y | N(14) | 요청일시 | |
| req_cnt | 고정값 : 1 | Y | N(5) | 입금요청건수주2) | |
| req_list | <object> | Y | 입금요청목록 | ||
| --tran_no | "1" | Y | N(5) | 거래순번 | |
| --bank_tran_id | "F123456789U4BC34239Z" | Y | AN(20) | 은행거래고유번호 | |
| --bank_code_std | "097" | Y | AN(3) | 입금은행.표준코드 | |
| --account_num | "1101230000678" | Y | AN(16) | 계좌번호 | |
| --account_seq | “001” | N | AN(3) | 회차번호 | |
| --account_holder_name | "홍길동" | Y | AH(20) | 입금계좌예금주명 | |
| --print_content | "입금계좌인자내역" | Y | AH(20) | 입금계좌인자내역 | |
| --tran_amt | "10000" | Y | N(12) | 거래금액 | |
| --req_client_name | “홍길동” | Y | AH(20) | 요청고객성명 | |
| --req_client_bank_code | "097" | N | AN(3) | 요청고객계좌 개설기관.표준코드 | |
| --req_client_account_num | "1101230000678" | N | AN(16) | 요청고객계좌번호 | |
| --req_client_fintech_use_num | "123456789012345678901234" | N | AN(24) | 요청고객핀테크이용번호 | |
| --req_client_num | “HONGGILDONG1234” | Y | AN(20) | 요청고객회원번호 | |
| --transfer_purpose | “TR” | Y | AN(2) | 이체용도 | |
| --recv_bank_tran_id | "F123456789U4BCT4112Z" | N | AN(20) | 수취조회 은행거래고유번호 | |
| --cms_num | “93848103221” | N | AN(32) | CMS 번호 |
주1) API 포털의 이용기관 환경설정 메뉴에서 설정하며, 담당자가 입력한 암호문구를 해시적용
(SHA-512)하여 생성
주2) 한번의 API 호출로 1건씩 입금 가능
요청 메시지 형태
{
"cntr_account_type": "N",
"cntr_account_num": "00012345678901234",
"wd_pass_phrase": "790d56ed........6b821a69",
"wd_print_content": "환불금액",
"name_check_option": "on",
"sub_frnc_name": “하위가맹점”,
"sub_frnc_num": “123456789012”,
"sub_frnc_business_num": “1234567890”,
"tran_dtime": "20190910101921",
"req_cnt": "1",
"req_list": [
{
"tran_no": "1",
"bank_tran_id": "F123456789U4BC34239Z",
"bank_code_std": "097",
"account_num": "1101230000678",
"account_holder_name": "홍길동",
"print_content": "쇼핑몰환불",
"tran_amt": "10000",
"req_client_name": “홍길동”,
"req_client_bank_code": "097",
"req_client_account_num": "00012300000678",
"req_client_num": “HONGGILDONG1234”,
"transfer_purpose": “TR”,
“recv_bank_tran_id”: "F123456789U4BCT4112Z",
“cms_num”: “93848103221”
}
]
}
응답 메시지 명세
| HTTP | 항목 | 값 | TYPE (길이) | 설명 |
|---|---|---|---|---|
| Body | api_tran_id | "2ffd133a-d17a-431d-a6a5" | aNS(40) | 거래고유번호(API) |
| api_tran_dtm | "20190910101921567" | N(17) | 거래일시(밀리세컨드) | |
| rsp_code | "A0000" | AN(5) | 응답코드(API) | |
| rsp_message | "" | AH(300) | 응답메시지(API) | |
| wd_bank_code_std | "097" | AN(3) | 출금기관.표준코드 | |
| wd_bank_code_sub | "1230001" | AN(7) | 출금기관.점별코드 | |
| wd_bank_name | "오픈은행" | AH(20) | 출금기관명 | |
| wd_account_num_masked | "000-1230000-***" | NS*(20) | 출금계좌번호(출력용) | |
| wd_print_content | "환불금액" | AH(20) | 출금계좌인자내역 | |
| wd_account_holder_name | "허균" | AH(20) | 송금인성명 | |
| res_cnt | "1" | N(5) | 입금건수 | |
| res_list | <object> | 입금목록 | ||
| --tran_no | "1" | N(5) | 거래순번 | |
| --bank_tran_id | "F123456789U4BC34239Z" | AN(20) | 거래고유번호(참가은행) | |
| --bank_tran_date | "20190910" | N(8) | 거래일자(참가은행) | |
| --bank_code_tran | "097" | AN(3) | 응답코드를 부여한 참가은행.표준코드 | |
| --bank_rsp_code | "000" | AN(3) | 응답코드(참가은행) | |
| --bank_rsp_message | "" | AH(100) | 응답메시지(참가은행) | |
| --bank_code_std | "097" | AN(3) | 입금(개설)기관.표준코드 | |
| --bank_code_sub | "1230001" | AN(7) | 입금(개설)기관.점별코드 | |
| --bank_name | "오픈은행" | AH(20) | 입금(개설)기관명 | |
| --savings_bank_name | “오픈저축은행” | AH(20) | 개별저축은행명 | |
| --account_num | "1101230000678" | AN(16) | 입금계좌번호 | |
| --account_seq | “001” | AN(3) | 회차번호 | |
| --account_num_masked | "000-1230000-***" | NS*(20) | 입금계좌번호(출력용) | |
| --print_content | "쇼핑몰환불" | AH(20) | 입금계좌인자내역 | |
| --account_holder_name | "홍길동" | AH(20) | 수취인성명 | |
| --tran_amt | "10000" | N(12) | 거래금액 | |
| --cms_num | “93848103221” | AN(32) | CMS 번호 |
응답 메시지 형태
{
"api_tran_id": "2ffd133a-d17a-431d-a6a5",
"api_tran_dtm": "20190910101921567",
"rsp_code": "A0000",
"rsp_message": "",
"wd_bank_code_std": "097",
"wd_bank_code_sub": "1230001",
"wd_bank_name": "오픈은행",
"wd_account_num_masked": "000-1230000-***",
"wd_print_content": "출금계좌인자내역",
"wd_account_holder_name": "허균",
"res_cnt": "1",
"res_list": [
{
"tran_no": "1",
"bank_tran_id": "F123456789U4BC34239Z",
"bank_tran_date": "20190910",
"bank_code_tran": "097",
"bank_rsp_code": "000",
"bank_rsp_message": "",
"bank_code_std": "097",
"bank_code_sub": "1230001",
"bank_name": "오픈은행",
"account_num": "1101230000678",
"account_num_masked": "000-1230000-***",
"print_content": "입금계좌인자내역",
"account_holder_name": "홍길동",
"tran_amt": "10000",
“cms_num”: “93848103221”
}
]
}
에러처리
오픈뱅킹으로부터 수신한 "응답코드(참가은행)"가 정상(000)이 아닌 경우에는 ‘이체 불능’으로 간주하되,
오픈뱅킹으로부터 응답을 받지 못했을 경우나 응답코드를 수신한 경우에는 API 명세서를 참고하여 처리 방법에 따라 처리해야 합니다.(자료실의 API 명세서
참고)
본관 : (우)04631 서울특별시 중구 퇴계로 110 (회현동3가)
분당센터 : (우)13556 경기도 성남시 분당구 정자일로213번길 9 (정자동)
Copyright ⓒ 2019 KFTC (Korea Financial Telecommunications & Clearings Institute)
All rights reserved.
