# 계좌 관리 ## 1. RegistBankAccount - 계좌 등록 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | -------------------------------------------------------------------- | --------------------------------------------------------------- | | POST | | | - 계좌조회 서비스를 이용할 계좌를 팝빌에 등록합니다. > 계좌를 등록할 때 결제기간만큼 포인트가 차감됩니다. 단, 파트너 포인트를 이용하는 경우에는 1개월 요금이 과금됩니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Query 파라미터** - UsePeriod `type: number` `length: 2` `required: N` `description: 정액제 이용할 개월수` - `1`: 1개월 : 기본값 - `2`: 2개월 - `3`: 3개월 - `4`: 4개월 - `5`: 5개월 - `6`: 6개월 - `7`: 7개월 - `8`: 8개월 - `9`: 9개월 - `10`: 10개월 - `11`: 11개월 - `12`: 12개월 - 파트너 포인트 사용시 입력값에 관계 없이 기본값 적용 **요청 본문** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` - AccountPWD `type: string` `length: 4` `required: Y` `description: 계좌 비밀번호` - AccountType `type: string` `length: 2` `required: Y` `description: 계좌 유형` - `법인` - `개인` - IdentityNumber `type: string` `length: 10` `required: Y` `description: 실명번호 ('-' 제외)` - {AccountType}="법인" 경우 사업자번호 - {AccountType}="개인" 경우 생년월일 (형식 : yyMMdd) - AccountName `type: string` `length: 100` `required: N` `description: 계좌 별칭` - BankID `type: string` `length: 50` `required: 조건부` `description: 인터넷뱅킹 아이디` - {BankCode}="0004"(국민은행) 경우 필수 - FastID `type: string` `length: 50` `required: 조건부` `description: 조회전용 계정 아이디` - {BankCode}="0031"(아이엠뱅크) or "0088"(신한은행) or "0048"(신협중앙회) 경우 필수 - FastPWD `type: string` `length: 50` `required: 조건부` `description: 조회전용 계정 비밀번호` - {BankCode}="0031"(아이엠뱅크) or "0088"(신한은행) or "0048"(신협중앙회) 경우 필수 - Memo `type: string` `length: 200` `required: N` `description: 메모` **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/EasyFin/Bank/BankAccount/Regist?UsePeriod={UsePeriod}' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "BankCode": "기관코드", "AccountNumber": "계좌번호", "AccountPWD": "계좌 비밀번호", "AccountType": "법인", "IdentityNumber": "실명번호", "AccountName": "계좌 별칭", "BankID": "인터넷뱅킹 아이디", "FastID": "조회전용 계정 아이디", "FastPWD": "조회전용 계정 비밀번호", "Memo": "메모" }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "등록 완료" } ``` ## 2. UpdateBankAccount - 계좌정보 수정 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | POST | | | - 팝빌에 등록된 계좌정보를 수정합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` **요청 본문** - AccountPWD `type: string` `length: 4` `required: Y` `description: 계좌 비밀번호` - AccountName `type: string` `length: 100` `required: N` `description: 계좌 별칭` - BankID `type: string` `length: 50` `required: 조건부` `description: 인터넷뱅킹 아이디` - {BankCode}="0004"(국민은행) 경우 필수 - FastID `type: string` `length: 50` `required: 조건부` `description: 조회전용 계정 아이디` - {BankCode}="0031"(아이엠뱅크) or "0088"(신한은행) or "0048"(신협중앙회) 경우 필수 - FastPWD `type: string` `length: 50` `required: 조건부` `description: 조회전용 계정 비밀번호` - {BankCode}="0031"(아이엠뱅크) or "0088"(신한은행) or "0048"(신협중앙회) 경우 필수 - Memo `type: string` `length: 200` `required: N` `description: 메모` **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/EasyFin/Bank/BankAccount/{BankCode}/{AccountNumber}/Update' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "AccountPWD": "계좌 비밀번호", "AccountName": "계좌 별칭", "BankID": "인터넷뱅킹 아이디", "FastID": "조회전용 계정 아이디", "FastPWD": "조회전용 계정 비밀번호", "Memo": "메모" }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "수정 완료" } ``` ## 3. GetBankAccountInfo - 계좌정보 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | GET | | | - 팝빌에 등록된 계좌 정보를 확인합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/EasyFin/Bank/BankAccount/{BankCode}/{AccountNumber}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - accountNumber `type: string` `length: 30` `description: 계좌번호` - bankCode `type: string` `length: 4` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - accountName `type: string` `length: 100` `description: 계좌 별칭` - accountType `type: string` `length: 2` `description: 계좌 유형` - `법인` - `개인` - state `type: number` `length: 1` `description: 계좌 상태` - `1`: 사용 - `2`: 정지 - regDT `type: string` `length: 14` `description: 팝빌에 계좌를 등록한 일시` - 형식 : yyyyMMddHHmmss - contractDT `type: string` `length: 14` `description: 정액제 서비스 시작일시` - 형식 : yyyyMMddHHmmss - useEndDate `type: string` `length: 8` `description: 정액제 서비스 만료일자` - 형식 : yyyyMMdd - baseDate `type: number` `length: 2` `description: 자동연장 결제일` - `5` - `15` - `25` - contractState `type: number` `length: 1` `description: 정액제 서비스 상태` - `1`: 사용 또는 사용제한 - `2`: 해지 - closeRequestYN `type: boolean` `length: -` `description: 정액제 서비스 해지신청 여부` - `true`: 신청 - `false`: 미신청 - useRestrictYN `type: boolean` `length: -` `description: 정액제 서비스 사용제한 여부` - `true`: 사용제한 - `false`: 사용 - closeOnExpired `type: boolean` `length: -` `description: 정액제 서비스 해지 구분` - `true`: 일반해지 (정액제 서비스 만료일 해지) - `false`: 중도해지 (요청 즉시 해지) - unPaidYN `type: boolean` `length: -` `description: 미수금 보유 여부` - `true`: 보유 - `false`: 미보유 - memo `type: string` `length: 200` `description: 메모` **응답 예시** ```json { "bankCode": "기관코드", "accountName": "계좌 별칭", "accountType": "법인", "accountNumber": "계좌번호", "state": 1, "regDT": "20251021102519", "memo": "메모", "contractState": 1, "closeRequestYN": false, "useRestrictYN": false, "closeOnExpired": false, "unPaidYN": false } ``` ## 4. ListBankAccount - 계좌정보 목록 조회 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | | GET | | | - 팝빌에 등록된 계좌정보 목록을 반환합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/EasyFin/Bank/ListBankAccount' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - accountNumber `type: string` `length: 30` `description: 계좌번호` - bankCode `type: string` `length: 4` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - accountName `type: string` `length: 100` `description: 계좌 별칭` - accountType `type: string` `length: 2` `description: 계좌 유형` - `법인` - `개인` - state `type: number` `length: 1` `description: 계좌 상태` - `1`: 사용 - `2`: 정지 - regDT `type: string` `length: 14` `description: 팝빌에 계좌를 등록한 일시` - 형식 : yyyyMMddHHmmss - contractDT `type: string` `length: 14` `description: 정액제 서비스 시작일시` - 형식 : yyyyMMddHHmmss - useEndDate `type: string` `length: 8` `description: 정액제 서비스 만료일자` - 형식 : yyyyMMdd - baseDate `type: number` `length: 2` `description: 자동연장 결제일` - `5` - `15` - `25` - contractState `type: number` `length: 1` `description: 정액제 서비스 상태` - `1`: 사용 또는 사용제한 - `2`: 해지 - closeRequestYN `type: boolean` `length: -` `description: 정액제 서비스 해지신청 여부` - `true`: 신청 - `false`: 미신청 - useRestrictYN `type: boolean` `length: -` `description: 정액제 서비스 사용제한 여부` - `true`: 사용제한 - `false`: 사용 - closeOnExpired `type: boolean` `length: -` `description: 정액제 서비스 해지 구분` - `true`: 일반해지 (정액제 서비스 만료일 해지) - `false`: 중도해지 (요청 즉시 해지) - unPaidYN `type: boolean` `length: -` `description: 미수금 보유 여부` - `true`: 보유 - `false`: 미보유 - memo `type: string` `length: 200` `description: 메모` **응답 예시** ```json [ { "bankCode": "기관코드", "accountName": "계좌 별칭", "accountType": "법인", "accountNumber": "계좌번호", "state": 1, "regDT": "20251021102519", "memo": "메모", "contractState": 1, "closeRequestYN": false, "useRestrictYN": false, "closeOnExpired": false, "unPaidYN": false } ] ``` ## 5. GetBankAccountMgtURL - 계좌 등록 팝업 URL | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------- | -------------------------------------------- | | GET | | | ![계좌 등록 팝업 URL 미리보기](https://developers.popbill.com/images/reference/easyfinbank/getBankAccountMgtURL.png) **계좌를 등록하는 팝업 URL을 반환합니다.** - 권장 사이즈 : width = 1,550px (최소 800px) / height = 680px - 반환되는 URL은 30초 동안만 사용이 가능합니다. - 반환되는 URL에서만 유효한 세션을 포함하고 있습니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Query 파라미터** - TG `type: string` `length: -` `required: Y` `description: 고정값 : BankAccount` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/EasyFin/Bank?TG=BankAccount' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - url `type: string` `length: -` `description: 계좌 등록 팝업 URL` **응답 예시** ```json { "url": "https://test.popbill.com/App/API?T=M5UKMNVIBABN7A3RPD3...ZNTKJP2Z75FWRLMME3QHUJR5NPF44IUQ=" } ``` ## 6. CloseBankAccount - 정액제 해지요청 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | POST | | | - 팝빌에 등록된 계좌의 정액제 해지를 요청합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Query 파라미터** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` - CloseType `type: string` `length: 2` `required: Y` `description: 정액제 해지 구분` - `일반`: 해지 요청일이 포함된 정액제 이용기간 만료 후 해지 **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/EasyFin/Bank/BankAccount/Close?BankCode={BankCode}&AccountNumber={AccountNumber}&CloseType={CloseType}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "해지요청 완료" } ``` ## 7. RevokeCloseBankAccount - 정액제 해지요청 취소 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- | | POST | | | - 신청한 정액제 해지요청을 취소합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Query 파라미터** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/EasyFin/Bank/BankAccount/RevokeClose?BankCode={BankCode}&AccountNumber={AccountNumber}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "해지요청 취소완료" } ``` ## 8. DeleteBankAccount - 계좌 삭제 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | -------------------------------------------------------------------- | --------------------------------------------------------------- | | POST | | | - 등록된 계좌를 삭제합니다. > 정액제가 아닌 종량제 이용 시에만 등록된 계좌를 삭제할 수 있습니다.\ > 정액제 이용시 [\[CloseBankAccount – 정액제 해지요청\]](https://developers.popbill.com/api-reference/easyfinbank/api/manage#CloseBankAccount) 함수를 사용하여 정액제를 해지할 수 있습니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/easyfinbank/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 본문** - BankCode `type: string` `length: 4` `required: Y` `description: 은행 기관코드` - [\[참고\] 조회 가능한 금융기관](https://developers.popbill.com/guide/easyfinbank/introduction/easy-intro#banklist) - AccountNumber `type: string` `length: 30` `required: Y` `description: 계좌번호` **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/EasyFin/Bank/BankAccount/Delete' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "BankCode": "기관코드", "AccountNumber": "계좌번호" }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "삭제 완료" } ```