Codream

1. 자금반환 API

이체입금 API가 정상적으로 작동됐으나, 거래가 완료된 입금이체에 대해 사용자가 착오송금 하거나 이용기관의 장애 등으로 자금 반환이 필요한 경우에 자금반환을 청구할 수 있습니다.

 테스트 환경이라면 응답정보 관리에 데이터를 추가한 뒤 금융결제원 swagger에서 Bearer Token(oob)설정 후 요청을 보냅니다.

{
  "bank_tran_id": "M123456789UBCDE12345",
  "org_bank_tran_date": "20220214",
  "org_bank_tran_id": "M123456789UBCDE12345",
  "org_dps_bank_code_std": "097",
  "org_dps_account_num": "0987654321098765",
  "org_tran_amt": "10000",
  "org_wd_bank_code_std": "097",
  "claim_code": "05",
  "claim_message": "시스템오류",
  "total_return_yn": "Y",
  "return_account_num": "1234567890123456",
  "use_org_contact": "010-1234-5678",
  "use_org_email": "testbed@kftc.or.kr"
}

요청 body

{
  "api_tran_id": "20d8600f-a50a-4dbe-9ffd-aac47415a12b",
  "api_tran_dtm": "20220215143901640",
  "rsp_code": "A0000",
  "rsp_message": "",
  "dps_bank_code_std": "097",
  "bank_tran_id": "M123456789U143901585",
  "bank_tran_date": "20190101",
  "bank_code_tran": "097",
  "bank_rsp_code": "000",
  "bank_rsp_message": "",
  "wd_bank_code_std": "097",
  "wd_bank_code_sub": "0970001",
  "wd_bank_name": "오픈은행",
  "org_bank_tran_date": "20220214",
  "org_bank_tran_id": "M123456789UBCDE12345",
  "org_dps_bank_code_std": "097",
  "org_dps_account_num": "0987654321098765",
  "org_dps_fintech_use_num": "",
  "org_tran_amt": "10000",
  "return_account_num": "1234567890123456"
}

응답

2. 자금반환 결과조회 API

 자금 반환 요청결과 확인이 필요한 경우 1년이내의 반환 결과를 확인하는 용도 입니다. 

 테스트 환경이라면 응답정보 관리에 데이터를 추가한 뒤 금융결제원 swagger에서 Bearer Token(oob)설정 후 요청을 보냅니다.

{
    "claim_bank_tran_date": 20220214,
    "claim_bank_tran_id":"M123456789UBCDE12345"
}

{
    "api_tran_id": "6df3cd1b-498c-4577-a960-178181e4e6c8",
    "rsp_code": "A0000",
    "rsp_message": "",
    "api_tran_dtm": "20220215151958528",
    "claim_bank_tran_date": "20220214",
    "claim_bank_tran_id": "M123456789UBCDE12345",
    "claim_normal_yn": "Y",
    "claim_bank_rsp_code": "000",
    "claim_bank_rsp_message": "내부오류",
    "return_yn": "Y",
    "return_fail_code": "00",
    "return_fail_message": "",
    "total_return_yn": "Y",
    "return_amt": "1000",
    "return_date": "20220215"
}

이전파트에서 테스트 준비를 끝냈으니, 이번에는 입금이체 API테스트를 진행해보고자 합니다.

1. 수취조회 API

 입금이체 요청 전 수취계좌의 입금가능 여부 및 수취인 성명을 사전에 조회합니다.

- Header의 Bearer는 테스트 준비단계에서 획득한 scope oob의 token을 기입해줍니다.

- 은행거래고유번호 : 

   My Page> 테스트 정보 관리 > '약정계정관리'탭의 수수료계좌 항목 中 '이용기관코드(10자리)' + "U" + **이용기관 부여번호 (9자리) 

여기서 **이용기관 부여번호는 하루동안의 유일성을 보장하는 무작위 코드를 의미합니다. 오픈뱅킹과 참가은행의 데이터 송수신시 요청을 구분할수있는 코드로 이용됩니다. 

 -약정계좌 : 

My Page> 테스트 정보 관리 >약정계정관리탭의 입금계좌정보 항목에 저장된 계좌정보를 가져와 기입합니다.

-입금은행, 표준코드

이외의 상호금융기관, 금융투자회사 코드는 해당 링크의 3.3에서 확인 가능합니다.

-요청고객 관련 정보

 제가 사용하고자 하는 환경은 구매자가 구매확정을 지었을때 이용기관 계좌에서 판매자의 계좌로 이체하고자 합니다. 때문에 여기에 해당하는 경우는 없으며, 이런 경우에는 요청고객정보를 이용기관의 정보를 기입해주시면 됩니다.

 상황에 따라 요청고객을 적절하게 설정해주신 후 '요청고객' 관련 정보에 기입해줍시다.

-이체용도

1.1 수취조회API 요청하기

데이터를 모두 기입했다면 이제 수취조회 API 요청을 보내봅시다.

금융 결제원 swagger의 /inquiry/receive API를 이용해 간편하게 테스트할 수 있습니다.

수취조회 API는 Header에 scope가 oob인 토큰을 필요로 합니다.

swagger의 자물쇠 버튼을 눌러 이전 파트에서 발급받았던 이용기관 토큰(oob)을 넣은 후 Authorize 버튼을 눌러주면 Header Authorization Bearer 토큰 설정이 완료 됩니다.

요청 Body에 정보를 채운 후 Execute합니다.

그러나 기대와는 다르게 다음과 같은 결과가 도출됩니다..

{
  "api_tran_id": "c225183e-1296-4a58-a78c-8a70114d1d05",
  "api_tran_dtm": "20220215110258699",
  "rsp_code": "A0002",
  "rsp_message": "참가기관 에러 [API업무처리시스템 - 시뮬레이터 응답전문 존재하지 않음]",
  "bank_code_std": "003",
  "bank_code_sub": "0000000",
  "bank_name": "IBK기업은행",
  "account_num": "12345678910875",
  "account_num_masked": "",
  "print_content": "구매확정",
  "account_holder_name": "",
  "bank_tran_id": "T123456789U110258646",
  "bank_tran_date": "20220215",
  "bank_code_tran": "098",
  "bank_rsp_code": "818",
  "bank_rsp_message": "시뮬레이터 응답전문 조회에 실패하였습니다",
  "wd_bank_code_std": "097",
  "wd_bank_name": "오픈은행",
  "wd_account_num": "200000000001",
  "tran_amt": "10000",
  "cms_num": "",
  "savings_bank_name": "",
  "account_seq": ""
}

테스트 API의 응답정보 관리에서 테스트용으로 사용할 데이터를 추가해주지 않았기 때문입니다. 

- MY PAGE > 테스트 정보 관리> 응답정보 관리 탭 선택후 API명에서 사용하고자 하는 API를 선택해 줍니다. 

- '데이터추가' 버튼 클릭 후 테스트 하고자 하는 데이터를 기입 후 저장합니다.

여기서 입금기관 대표코드, 입금계좌번호, 입금계좌인자내역은 각각 수취 요청 body의 bank_code_std, account_num, print_content에 입력해줄 값 입니다.

 응답정보 저장이 끝났다면, 다시 수취 요청을 보내봅시다.

{
    "api_tran_id": "199f3b55-5fc3-412c-b062-9f5d474ee86b",
    "api_tran_dtm": "20220215125626097",
    "rsp_code": "A0000",
    "rsp_message": "",
    "bank_code_std": "097",
    "bank_code_sub": "0000000",
    "bank_name": "오픈은행",
    "account_num": "0123456798123456",
    "account_num_masked": "0123456798123***",
    "print_content": "구매확정",
    "account_holder_name": "김판매자",
    "bank_tran_id": "M123456789U4BC342404",
    "bank_tran_date": "20190101",
    "bank_code_tran": "097",
    "bank_rsp_code": "000",
    "bank_rsp_message": "",
    "wd_bank_code_std": "097",
    "wd_bank_name": "오픈은행",
    "wd_account_num": "1234567890123456",
    "tran_amt": "10000",
    "cms_num": "",
    "savings_bank_name": "",
    "account_seq": ""
}

 성공적으로 응답이 돌아옵니다. 수취 조회 뿐만아니라, 다른 API(사용자 인증, 토큰 발급 제외) 테스트 또한 응답정보 저장이 되어있어야 응답 결과가 정상적으로 반환됩니다.

 수취 조회 API는 입금이체 요청 전 수취계좌의 입금가능 여부 및 수취인 성명을 사전에 조회하는 API로, 응답의 acount_holder_name 으로 수취인 성명을 확인할 수 있으며, rsp_code는 A0000이외의 값, bank_rsp_code는 000 이외의 값이 들어가면 수취계좌의 입금이 불가능하며 그에 따른 메세지는 각각 rsp_message, bank_rsp_message로 전달됩니다.

2. 입금이체 API

 이용기관이 사용자의 계좌로 대금을 송금합니다. 

- 실 계좌번호로 요청 : /acnt_num

- 핀테크 이용번호로 요청 :  /fin_num

2.1. 입금이체 : 계좌번호로 요청

- 입금 이체용 암호문구 :

테스트 환경이므로 "NONE"으로 설정하겠습니다.

- 요청 고객 핀테크 이용번호 : 요청고객의 계좌번호 및 계좌 개설 기관 코드를 알지 못하는 이용기관의 경우 요청고객의 핀테크 이용번호를 세팅해야 하며, 핀테크 번호와 계좌관련 정보를 둘다 세팅할 경우 오류가 발생합니다.

이번에도 역시 금융 결제원 swagger의 /transfer/deposit/acnt_num API를 이용하겠습니다. 입금이체 API사용전 응답정보 데이터를 추가해주시는것 잊지마세요! 자물쇠 버튼을 눌러 Bearer가 등록되어있는것을 확인한후, 요청 Body를 작성합니다.

{
  "cntr_account_type": "N",
  "cntr_account_num": "200000000001",
  "wd_pass_phrase": "NONE",
  "wd_print_content": "구매확정",
  "name_check_option": "on",
  "tran_dtime": "20220215133400",
  "req_cnt": "1",
  "req_list": [
    {
      "tran_no": "1",
      "bank_tran_id": "M2123456789U4BC342502",
      "bank_code_std": "097",
      "account_num": "0123456798123456",
      "account_holder_name": "김판매자",
      "print_content": "구매확정",
      "tran_amt": "1000",
      "req_client_name": "테스트",
      "req_client_bank_code": "097",
      "req_client_account_num": "000000000001",
      "req_client_num": "M2123456789",
      "transfer_purpose": "TR"
    }
  ]
}

요청 body 

2.2. 입금이체 : 핀테크 이용번호 요청

 핀테크 이용번호(fintech_use_num)는 사용자가 사용자 인증, 토큰발급을 마친경우 사용자 정보조회 API를 이용해서 확인 가능하며, 이용기관에서는 이때 확인한 핀테크 이용번호를 DB에 따로 저장하거나, 필요시에 사용자 정보조회 API를 호출하여 핀테크 이용번호를 가져와서 사용해야합니다.

{
  "cntr_account_type": "N", 
  "cntr_account_num": "200000000001", 
  "wd_pass_phrase": "NONE",
  "wd_print_content": "환불금액", 
  "name_check_option": "off", 
  "tran_dtime": "20220211164900", 
  "req_cnt": "1", 
  "req_list": [
    {
      "tran_no": "1", 
      "bank_tran_id": "M123456789U002111651", 
      "print_content": "오픈서비스캐시백", 
      "fintech_use_num" : "123412344588941097876418",
      "tran_amt": "500", 
      "req_client_name": "우리회사", 
      "req_client_bank_code": "097", 
      "req_client_account_num": "012345678912345", 
      "req_client_num": "M123456789", 
      "transfer_purpose": "TR"
    }
  ]
}

2.2. 입금이체 : 응답 결과

{
    "api_tran_id": "9fe18ee5-181d-4ddc-9dda-c8359a87c4f6",
    "rsp_code": "A0000",
    "rsp_message": "",
    "api_tran_dtm": "20220215134043034",
    "wd_bank_code_std": "097",
    "wd_bank_code_sub": "0970001",
    "wd_bank_name": "오픈은행",
    "wd_account_num_masked": "1234567890123***",
    "wd_print_content": "홍길동캐시백",
    "wd_account_holder_name": "김오픈",
    "res_cnt": "1",
    "res_list": [
        {
            "tran_no": "1",
            "bank_tran_id": "M123456789U4BC342502",
            "bank_tran_date": "20190101",
            "bank_code_tran": "097",
            "bank_rsp_code": "000",
            "bank_rsp_message": "",
            "bank_code_std": "097",
            "bank_code_sub": "0000000",
            "bank_name": "오픈은행",
            "account_num": "0123456798123456",
            "account_num_masked": "0123456798123***",
            "print_content": "구매확정",
            "tran_amt": "1000",
            "account_holder_name": "김판매자",
            "cms_num": "",
            "savings_bank_name": "",
            "account_seq": ""
        }
    ]
}

응답 전문

 wd_print_content, wd_account_holder_name, bank_tran_date는 의도한대로 전달되지는 않았지만, 테스트 환경이라서 이처럼 전달되는것으로 보입니다. 응답코드(rsp_code : A0000), 참가은행 응답코드(bank_rsp_code : 000) 처리성공으로 떨어졌기 때문에 테스트 성공으로 판단합니다. 

3. 이체결과조회 API

 입금이체 후 이체 결과를 다시 확인합니다. 이체시 비 정상적인 응답코드를 받았을 경우, 응답을 받지 못했을경우 1개월 이내 이체건에 대해 이체결과를 다시 확인할 수 있습니다.

이체결과조회 응답정보 데이터를 추가, 자물쇠 버튼을 눌러 Bearer가 등록되어있는것을 확인한후, 요청 Body를 작성합니다.

-req_cont : 한번에 최대 25건을 확인 가능하며, req_cnt와 req_list목록의 검색 항목 수가 같지 않으면 오류를 반환합니다

{
    "check_type" : "2",
    "tran_dtime" : "20220214103400",
    "req_cnt" : "002",
    "req_list" :[
        {
            "tran_no" : "1",
            "org_bank_tran_id" : "M123456789U002111756",
            "org_bank_tran_date" : "20220214",
            "org_tran_amt" : "1500"
        },
        {
            "tran_no" : "2",
            "org_bank_tran_id" : "M123456789U002111755",
            "org_bank_tran_date" : "20220214",
            "org_tran_amt" : "500"
        }
    ]
}

요청 body

{
    "api_tran_id": "de3d654e-ffb6-4db7-ac7f-bd6e1d5fb827",
    "rsp_code": "A0000",
    "rsp_message": "",
    "api_tran_dtm": "20220215135638640",
    "res_cnt": "2",
    "res_list": [
        {
            "tran_no": "1",
            "bank_tran_id": "M123456789U002111756",
            "bank_tran_date": "20220214",
            "bank_code_tran": "097",
            "bank_rsp_code": "000",
            "bank_rsp_message": "",
            "wd_bank_code_std": "097",
            "wd_bank_code_sub": "0970001",
            "wd_bank_name": "오픈은행",
            "wd_fintech_use_num": "",
            "wd_account_num_masked": "",
            "wd_print_content": "출금계좌인자샘플",
            "wd_account_holder_name": "",
            "dps_bank_code_std": "097",
            "dps_bank_code_sub": "0000000",
            "dps_bank_name": "오픈은행",
            "dps_fintech_use_num": "",
            "dps_account_num_masked": "",
            "dps_print_content": "입금계좌인자샘플",
            "dps_account_holder_name": "",
            "tran_amt": "1500",
            "wd_savings_bank_name": "",
            "dps_savings_bank_name": ""
        },
        {
            "tran_no": "1",
            "bank_tran_id": "M123456789U002111755",
            "bank_tran_date": "20220214",
            "bank_code_tran": "097",
            "bank_rsp_code": "000",
            "bank_rsp_message": "",
            "wd_bank_code_std": "097",
            "wd_bank_code_sub": "0970001",
            "wd_bank_name": "오픈은행",
            "wd_fintech_use_num": "",
            "wd_account_num_masked": "",
            "wd_print_content": "출금계좌인자샘플",
            "wd_account_holder_name": "",
            "dps_bank_code_std": "097",
            "dps_bank_code_sub": "0000000",
            "dps_bank_name": "오픈은행",
            "dps_fintech_use_num": "",
            "dps_account_num_masked": "",
            "dps_print_content": "입금계좌인자샘플",
            "dps_account_holder_name": "",
            "tran_amt": "500",
            "wd_savings_bank_name": "",
            "dps_savings_bank_name": ""
        }
    ]
}

응답전문

1. 테스트 계정 생성

금융 결제원에서 제공하는 개발자 사이트의 테스트 베드를 이용하면 

금융결제원의 다양한 API서비스를 편리하게 개발 및 테스트 가능합니다.

본격적인 테스트에 들어가기 앞서, 다음 링크에서 먼저 가입해줍니다.

https://developers.kftc.or.kr/dev/login

2. 테스트 환경 설정

 정상적으로 회원가입이 완료 되었다면 MY PAGE> 내 서비스 관리 탭을 타고 들어가 테스트 할 서비스(오픈뱅킹, 오픈지로, 온투업중앙기록관리 등)의 신청 버튼을 눌러 '이용중'상태로 바꿔줍니다.

 다음, API Key관리 탭으로 이동하여 Callback URL을 입력 후 저장버튼 클릭후 서비스 별 Callback URL등록 버튼을 클릭해 '완료'상태로 바꿔줍니다. 여기서 Callback URL은 API이용 시 사용자인증이 완료되면 리다이렉트할 URL을 넣어줍니다.

 여기서 Client ID, Client Secret, Callback URL은 API 요청시 필요한 정보들이니 따로 메모해두는것이 좋습니다.

2-1. 약정 계좌 관리

테스트 정보 관리> 약정계좌 관리탭에서  테스트용 계좌 정보를 등록합니다.

입금계좌 : 입금이체 API 이용 시 필요한 이용기관의 출금용 지급계좌 정보를 등록합니다.

출금계좌 : 출금이체 API 이용 시 필요한 이용기관의 입금용 수납계좌 정보를 등록합니다.

3. 사용자 인증

 테스트 API를 사용하기 위해서는 사용자 인증 및 약정계좌 관리등 절차가 필요합니다. 테스트 사용자의 계좌를 등록하고, Token을 발급받아 사용자 권한의 오픈뱅킹 API를 테스트 해 볼수 있습니다.

  위는 요청토큰의 권한에 따라 접근할 수 있는 API를 분류 해 놓았으며, 자체인증 이용기관의 API나 더욱 상세한 정보를 보고자 한다면 API 명세를 함께보시는것을 적극 추천드립니다.

 사용자인증(OAuth 2.0)은 3-legged 인증과 2-legged 인증으로 구분됩니다.

 3-legged 인증은 사용자가 이용기관의 앱을 통하여 오픈뱅킹 서비스에 접근하기 위한 인증 기능을 제공합니다. 사용자는 오픈뱅킹(Service Provider)의 인증 페이지에서 본인인증 및 조회/출금동의를 통하여 인증하고, 이용기관은 사용자에 대한 Access Token을 얻음으로써 사용자의 인증을 획득합니다.

 2-legged 인증은 사용자의 개입 없이 단순히 이용기관이 자신에 대한 인증정보(Client ID, Client Secret)를 가지고 인증함으로써, 오픈뱅킹으로부터 이용기관에 대한 Access Token을 획득하는 것을 의미합니다.

3-1. 사용자 인증 (3-legged)

 API를 테스트 하기에 앞서 요청 권한(Token)을 얻기위해 인증을 실시해줍시다.

금융결제원에서 제공해주는 Swagger를 이용하여 간편하게 테스트 가능하며, Postman을 이용하여 직접 작성해도 문제없습니다.

  우리는 테스트 API로 호출하여 과금되는일이 없도록 주의합시다. 

테스트용 메시지 URL은 https://testapi.openbanking.or.kr/oauth/2.0/authorize로 작성합니다. 

- client_id, redirect_uri는 2. 테스트 환경설정에 있는 값들을 기입합니다. 

- scope : 3.사용자 인증의 권한범위 이미지를 참고하여 원하는 scope를 기입합니다(login inquiry, login transfer, login inquiry transfer)

- state : 32byte의 난수값을 입력한다. 32byte가 차지 않으면 파라미터 에러가 발생. 

※ auth_type 별 필수요소를 꼭 확인 후 API를 호출합시다. 

•  swagger 호출결과

Postman 호출결과

  정상적인 시스템 흐름이라면 Redirect되는 페이지에서 Parameter를 넘겨받아 바로 토큰발급 API를 실행시켜주는것이 맞지만, 지금은 테스트 환경이고 만들어진 화면도 없어 아무 URL이나 입력했습니다(그렇다고 진짜 실행되는 도메인은 피해주세요). 따로 화면이 표시되지 않더라도 URL에서 파라미터로 넘어온 값들을 확인할 수 있습니다.

(ex. http://localhost:8080/test?code=o9MztBS3fysYiep6z34cph******&scope=inquiry%20login%20transfer &client_info=test &state=b80BLsfigm9OokPTjy03elbJqRHOfGSY)

3-2. 토큰발급(사용자 토큰발급 요청)

 - code :  3-1)작업후 전달받은 Parameter중 code값을 기입합니다.

 - client_id, client_secret, redirect_uri : 2)에서 메모한 값을 기입해줍니다.

 - 요청 성공시 전달받은 access_token, refresh_token, user_seq_no를 잘 저장해두고 테스트시 유용하게 사용합시다.

3-3. 토큰발급(이용기관 토큰발급 요청)

 이용기관은 사용자인증 API의 호출없이 바로 /token API를 호출하여 토큰을 획득합니다.

- client_id, client_secret : 2)에서 메모한 값을 기입해줍니다.

- scope : sa(자체인증기관), oob(센터인증기관) 

 - oob, sa scope는 refresh를 지원하지 않기때문에 응답에 refresh token이 없습니다. API설계시, expires_in(만료기간)을 이용해 적절하게 토큰관리가 이루어져야 합니다.

이제 테스트를 위한 준비가 완료되었습니다.