변경이력
버전 | 날짜 | 변경사항 |
v20240508_1 | 20240508 | 최초작성 |
v20240509_1 | 20240509 | merchant.realOwnerVerificationSkipType 파람 제거 |
v20240618_1 | 20240618 | 3.1.2 항목 삭제 (response 가 별도로 나가고있지 않은 api 라 삭제함) |
v20250430_1 | 20250430 | 3.1.1 merchant.aml.largestStakeholderType 항목 중 사용하지 않는 ELECTED 제외 |
1. 개요
토스페이먼츠 컴플이슈 해결을 위해 추가정보 수취가 필요하여 버전업된 정보업데이트 API입니다
카페24페이먼츠 에서 사용합니다
이 문서는 싱크 협의후에 원본독스로 갱신되어 합쳐집니다
카페24페이먼츠 업데이트 V2 API 스펙
3.1. 사업자/상점 정보업데이트 api 호출 (카페24 → 토스페이먼츠)
3.1.1. Request
PUT /merchants/api/v2/secondary-pg/onboarding/merchant/{카페24에서 사용하는 사업자번호와 동등레벨의 식별자}
Name | Type | Required | Description |
merchant | Object | - | 사업자 정보 (null 이 아닐 경우 업데이트) |
merchant.realOwnerVerificationSkipType | String | N | 실제소유자 생략 시 생략 유형
* FINANCIAL_SERVICES_COMPANY (금융회사)
* GOVERNMENT (국가지방자치단체)
* PUBLIC_ORGANIZATION (공공단체)
* LISTED_COMPANY (상장사)
* NONE (해당없음)
아래 동일한 값을 수취하는 파람이 존재하여 제거
merchant.aml.organizationType |
merchant.business.companyName | String | Y | 상호명 국문 |
merchant.business.companyEnglishName | String | Y | 상호명 영문 |
merchant.business.companyNationality | String | Y | 사업장 국적 |
merchant.business.corporateNumber | String | N | 법인번호 |
merchant.business.foundedDate | LocalDate | Y | 회사설립일 |
merchant.business.companyType | String | Y | * CORPORATE(법인사업자)
* PRIVATE(일반사업자)
* NON_PROFIT_CORP(비영리법인)
* NON_PROFIT(공공단체) |
merchant.business.registeredBusinessType | String | Y | 사업자등록증상 업태 |
merchant.business.registeredBusinessItem | String | Y | 사업자등록증상 종목 |
merchant.business.address.postalCode | String | Y | 사업장 우편번호 |
merchant.business.address.main | String | Y | 사업장 주소 |
merchant.business.address.detail | String | N | 사업장 상세주소 |
merchant.business.headOfficeAddress.postalCode | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 우편번호 |
merchant.business.headOfficeAddress.main | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 주소 |
merchant.business.headOfficeAddress.detail | String | N | 본점 상세주소 |
merchant.business.headOfficeNationality | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 소재국가 |
merchant.aml.establishmentPurpose | String | N
(비영리법인/단체 일 경우 Y) | 설립목적
* ACADEMIC(학술)
* RELIGION(종교)
* CHARITY(자선)
* CULTURE(문화)
* EDUCATION(교육)
* SOCIAL(사회사업)
* NATION(국가기관 등)
* ETC(기타)
※ 개인사업자/영리법인일 경우에 필요없음 : null |
merchant.aml.establishmentPurposeDescription | String | N
(merchant.aml.establishmentPurpose이 ETC일 경우 Y) | 설립목적 기타일시 자유입력텍스트
※ 개인사업자/영리법인일 경우에 필요없음 : null |
merchant.aml.tradePurpose | String | Y | 거래목적 |
merchant.aml.cashSource | String | Y | 자금출처 |
merchant.aml.isMajorCompany | Boolean | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 대기업여부
※ 개인사업자일 경우에 필요없음 : null |
merchant.aml.listedStockMarket | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 상장여부+거래소정보
* HKEX(홍콩증권거래소)
* LSE(런던증권거래소)
* KOSPI(코스피)
* NASDAQ(나스닥)
* KOSDAQ(코스닥)
* NYSE(뉴욕증권거래소)
* ETC(기타)
* NONE(비상장)
※ 개인사업자일 경우에 필요없음 : null |
merchant.aml.listedStockMarketDescription | String | N
(merchant.aml.listedStockMarket이 ETC일 경우 Y) | 상장거래소 정보 기타일시 자유입력텍스트
※ 개인사업자일 경우에 필요없음 : null |
merchant.aml.isVirtualCurrency | Boolean | Y | 가상자산사업자여부 |
merchant.aml.organizationType | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 법인/단체 분류
* NATION(국가지방자치단체)
* PUBLIC(공공단체)
* FINANCE(금융회사)
* LISTED(상장사)
* NONE(해당없음)
※ 개인사업자일 경우에 필요없음 : null |
merchant.aml.largestStakeholderType | String | N
(영리법인, 비영리법인/단체 일 경우 Y) | 실제소유주 구분타입
* OVER_25_STAKE (25%이상 지분소유주)
* LARGEST_AMONG_UNDER_25_STAKE (25%미만이지만 최대지분소유주)
* ELECTED (선임된 대표 또는 이해관계자)
* NOT_LARGEST_BUT_BIG_SHOT (실세)
* NONE (실제소유주=대표자)
※ 개인사업자일 경우에 필요없음 : null
※ 법인 분류가 NONE 이 아닌 경우 필요없음 :null
|
merchant.representatives[] | Array | Y | 대표자 |
merchant.representatives[].koreanName | String | Y | 대표자 국문명 |
merchant.representatives[].englishName | String | Y | 대표자 영문명 |
merchant.representatives[].birthDate | String | Y | 대표자 생년월일 (240101 ← 이런형식 YYMMDD) |
merchant.representatives[].genderCode | String | Y | 대표자 성별코드
뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기 |
merchant.representatives[].nationality | String | Y | 대표자 국적
2자리 국가코드 (EX:KR) |
merchant.representatives[].residenceNationality | String | N | 대표자 거주지 국가 |
merchant.representatives[].address.postalCode | String | N | 대표자 거주지 우편번호 |
merchant.representatives[].address.main | String | N | 대표자 거주지 주소 |
merchant.representatives[].address.detail | String | N | 대표자 거주지 상세주소 |
merchant.representatives[].phoneNumber | String | N | 대표자 전화번호 |
merchant.representatives[].email | String | N | 대표자 이메일 |
merchant.representatives[].occupation | String | N | 대표자 직업
- 개인사업자일 경우 필수. 여러가지 타입이 있으나 “자영업자"" 고정으로 보내주셔도 무방해요
- 법인사업자일경우 제외
존재하는케이스
* EMPLOYED 직장인
* SELF_EMPLOYED 자영업자
* UNEMPLOYED 무직
* STUDENT 학생
* HOUSEWIFE 주부
* GAMBLING_FACILITY_OPERATOR 사행시설 운영업 종사자
* ONLINE_GAMBLING_BUSINESS_WORKER 온라인 갬블링 사업 종사자
* LOAN_BUSINESS_WORKER 대부업 종사자
* CASINO_BUSINESS_WORKER 카지노사업 종사자
* MONEY_EXCHANGE_BUSINESS_WORKER 환전영업 종사자
* SMALL_AMOUNT_OVERSEAS_REMITTANCE_BUSINESS_WORKER 소액해외송금업 종사자
* VIRTUAL_ASSET_BUSINESS_WORKER 가상자산사업 종사자
* INTERNATIONAL_OR_FOREIGN_INSTITUTION_WORKER 국제 및 외국기관 종사자
* PRECIOUS_METAL_SALES_WORKER 귀금속 판매상 종사자
* TRUST_BUSINESS_WORKER 신탁업 종사자
* OTHERS 기타 |
merchant.actualOwners[] | Array | Y | 실제소유주 |
merchant.actualOwners[].entityType | String | Y | 실제소유주 타입
* INDIVIDUAL(개인)
* CORPORATION(법인)
// 법인소유주 케이스가 없다면, 개인소유주 타입 고정으로 보내주셔도 무방합니다 |
merchant.actualOwners[].koreanName | String | Y | 실제소유주 이름 국문 |
merchant.actualOwners[].englishName | String | Y | 실제소유주 이름 영문 |
merchant.actualOwners[].birthDate | String | N
(실제소유주가 개인이면 Y) | 실제소유주 생년월일 (240101 ← 이런형식 YYMMDD)
※ 실소유자 타입이 법인인 경우엔 필요없습니다. (법인은 foundedDate가 필수) |
merchant.actualOwners[].genderCode | String | N
(실제소유주가 개인이면 Y) | 실제소유주 성별코드
뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기
※ 실소유자 타입이 법인인 경우엔 필요없습니다. (법인은 성별이없음) |
merchant.actualOwners[].nationality | String | Y | 개인인 경우 : 실제소유주 국적
법인인 경우 : 사업장 소재지국적 |
merchant.actualOwners[].residenceNationality | String | N
(실제소유주가 개인이면 Y) | 실제소유주 거주지 국가
※ 실소유자 타입이 법인인 경우엔 필요없습니다. |
merchant.actualOwners[].ratioOfStake | Number | Y | 실제소유주 지분율 (**100을초과할수없습니다) (예시: 33.25, 24, 100) |
merchant.actualOwners[].foundedDate | String | N
(실제소유주가 법인이면 Y) | 법인 설립일자
※ 실소유자 타입이 개인인 경우엔 필요없습니다. |
merchant.actualOwners[].organizationType | String | N
(실제소유주가 법인이면 Y) | 실제소유주 법인 분류
* NATION(국가지방자치단체)
* PUBLIC(공공단체)
* FINANCE(금융회사)
* LISTED(상장사)
* NONE(해당없음)
※ 실소유자 타입이 개인인 경우엔 필요없습니다. |
merchant.actualOwners[].certificateType | String | Y | 실제소유주 증빙서류 유형
* SHAREHOLDERS_LIST (주주명부)
* DART_DOCUMENT (전자공시)
* DART_REPORT (DART 공시자료)
* ARTICLES_OF_ORGANIZATION (정관)
* CORPORATE_REGISTRATION (등기부등본)
* MEETING_MINUTES (회의록)
* OFFICIAL_DOCUMENT (공문) |
merchant.attachment[] | Array | Y | 사업자 단위 첨부 서류 |
merchant.attachment[].type | String | Y | 사업자 단위 첨부 서류 종류
[기존서류 한글이넘으로 교체//한글이넘입니다]
* 사업자등록증_또는_고유번호증 : 사업자등록증 또는 고유번호증
* 대표자_신분증 : 대표자신분증
* 주주명부 : 주주명부
* 추가_보완_서류 : 사업자단위 추가보완서류
* COPY_OF_BANK_ACCOUNT : 통장사본 (이 서류타입만 영문이넘 유지)
* 법인등기사항전부증명서: 법인등기부등본(법인등기사항전부증명서)
//아래내용은 6월 이후 협의예정
[기존 추가서류로 주고있었으나 앞으로는 타입에맞게보내줘야하는 서류/한글이넘]
/* 아래 타입의 서류들은 별도로 구분하시고 계시다면 알맞은 타입으로 보내주세요*/
* 대표자_외국인등록증
* 대표자_여권 (개인사업자의 대표자가 외국인이면 여권도같이보내주세요)
* 대표자_인감증명서
* 공동_대표자_신분증 (법인인경우에만 보내주세요.개인사업자는공동대표자정보필요X)
* 공동_대표자_외국인등록증 (법인인경우에만 보내주세요.개인사업자는공동대표자정보필요X)
* 공동_대표자_여권 (법인인경우에만 보내주세요.개인사업자는공동대표자정보필요X)
* 실_소유자_증빙_서류 (정관,이사회명부,주주명부 외 실소유자 확인가능한 서류)
* 설립목적_증빙_서류
* 정관
* 공동_대표자_법인_인감증명서
* 대표자_법인_인감증명서
* 인감미제출_확인서
* 이사회_명부
* 법인_인감_증명서_또는_인감미제출_특수법인_합의서
* 법정_대리인_동의서 (대표자가 미성년자인경우 필요)
* 법정_대리인_개인_인감증명서 (대표자가 미성년자인경우 필요)
* 가족관계_기록사항에_관한_증명서 (대표자가 미성년자인경우 필요) |
merchant.attachment[].url | String | Y | 사업자 단위 첨부 서류 URL
※ 200자 내의 url만 허용(200자 제한) |
shop | Object | - | 상점 정보 (null 이 아닐 경우 업데이트) |
shop.pid | String | Y | 상점 PID |
shop.url | String | Y | 상점 URL |
shop.contactName | String | Y | 계약담당자 이름 |
shop.contactEmail | String | Y | 계약담당자 이메일 |
shop.contactPhoneNumber | String | Y | 계약담당자 전화번호 |
shop.attachment[] | Array | Y | 상점 단위 첨부 서류 |
shop.attachment[].type | String | Y | 상점 단위 첨부 서류 종류 (한글 이넘입니다)
* 공동_대표자_위임장 : 공동 대표자 위임장
* 공동_대표자_인감증명서 : 공동 대표자 인감증명서
* 상점_단위_추가_보완_서류 : 상점 단위 추가 보완 서류 |
shop.attachment[].url | String | Y | 상점 단위 첨부 서류 URL
※ 200자 내의 url만 허용(200자 제한) |
shop.bankAccount | Object | N | 정산계좌 |
shop.bankAccount.bankCode | String | Y | 정산계좌 계좌 코드
금융결제원 [대표코드 및 기관코드] 참조 https://www.kftc.or.kr/kftc/data/EgovBankList.do |
shop.bankAccount.accountNumber | String | Y | 정산계좌 계좌번호 |
shop.bankAccount.accountHolder | String | Y | 정산계좌 예금주 |
shop.phoneNumber | String | Y | 가맹점 대표전화번호 |
shop.reviewRequired | Boolean | Y | 심사 요청 여부 |