변경이력
버전 | 날짜 | 변경사항 |
v20240709_1 | 20240709 | v3최초작성 |
개요
토스페이먼츠 컴플이슈 해결을 위해 추가정보 수취가 필요하여 버전업된 정보업데이트 API입니다
카페24페이먼츠 에서 사용합니다
이 문서는 싱크 협의후에 원본독스로 갱신되어 합쳐집니다
카페24페이먼츠 업데이트 V3 API 스펙
대리인 이슈 해결을 위해 대리인 정보를 추가 수취할 수 있도록 스펙이 확장되었습니다.
사업자/상점 정보업데이트 api 호출 (카페24 → 토스페이먼츠)
Request
PUT /merchants/api/v3/secondary-pg/onboarding/merchant/{카페24에서 사용하는 사업자번호와 동등레벨의 식별자}
Name | Type | Required | Description |
merchant | Object | - | 사업자 정보 (null 이 아닐 경우 업데이트) |
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.applicant | Object | Y | 신청인 정보 |
shop.applicant.koreanName | String | Y | 신청인 한국이름 |
shop.applicant.englishName | String | Y | 신청인 영문이름 |
shop.applicant.phoneNumber | String | Y | 신청인 휴대폰번호 |
shop.applicant.email | String | Y | 신청인 이메일 |
shop.applicant.birthDate | String | Y | 신청인 생년월일 (240101 ← 이런형식 YYMMDD) |
shop.applicant.genderCode | String | Y | 신청인 성별코드
뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기 |
shop.applicant.deputy | Object | N | 대리인 정보 (신청인이 대표자가 아닌경우 필수) |
shop.applicant.deputy.koreanName | String | Y | 대리인 한국이름 |
shop.applicant.deputy.englishName | String | Y | 대리인 영문이름 |
shop.applicant.deputy.nationality | String | Y | 국적코드 |
shop.applicant.deputy.address | Object | Y | 대리인 주소 정보 |
shop.applicant.deputy.address.postalCode | String | Y | 대리인 거주지 우편번호 |
shop.applicant.deputy.address.main | String | Y | 대리인 거주지 주소 |
shop.applicant.deputy.address.detail | String | N | 대리인 거주지 상세주소 |
shop.applicant.deputy.occupation | String | Y | 대리인 직무(회사와의 관계)
ex) 토스페이먼츠에서는 ‘정산담당자’, ‘운영담당자’,’협력사 혹은 외주사직원’등의 선택지를 제공하나, 자유입력 텍스트로도 기재가능합니다. 만약 참고가 필요하시면 토스페이먼츠 선택지 항목 전달드리겠습니다. |
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 | 심사 요청 여부 |
카페24페이먼츠 신청인(대리인) 본인인증 API 스펙
상점 신청인 본인인증 인증코드 요청 api 호출 (카페24 → 토스페이먼츠)
Request
POST /merchants/api/v1/secondary-pg/merchant/{카페24에서 사용하는 사업자번호와 동등레벨의 식별자}/personal-identity-authentication/request
requestBody
Name | Type | Required | Description |
pid | String | Y | 카페24 PID |
name | String | Y | 인증 요청자 이름 |
birthDate | String | Y | 신청인 생년월일 (240101 ← 이런형식 YYMMDD) |
genderCode | String | Y | 신청인 성별코드
뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기 |
phoneCarrier | String | Y | 통신사코드
통신 3사 - SK, LGU, KT
알뜰폰 - SK_MVNO, LGU_MVNO, KT_MVNO |
responseBody
Name | Type | Description |
nextRequestAvailableAt | OffsetDateTime | 다음 요청 가능 시간
ex) 2024-07-09T14:24:01.677333008+09:00 |
requesterPhoneNumber | String | 본인인증 요청 휴대폰번호 |
authToken | String | 인증토큰 |
authTokenExpiresAt | OffsetDateTime | 인증토큰 만료시간
ex) 2024-07-09T14:24:01.677333008+09:00 |
상점 신청인(대리인) 본인인증 인증코드 확인
계약 전 상점의 신청인 본인인증 인증코드 확인 API (카페24 → 토스페이먼츠)
Request
POST /merchants/api/v1/secondary-pg/merchant/{카페24에서 사용하는 사업자번호와 동등레벨의 식별자}/personal-identity-authentication/confirm
requestBody
Name | Type | Required | Description |
pid | String | Y | 카페24 PID |
authToken | String | Y | 본인인증 인증코드 요청시 발급된 authToken |
authCode | String | Y | 고객이 입력한 6자리 숫자코드 |
추가되는 에러코드
INVALID_REGISTRATION_NUMBER | 사업자 번호 유효성 검증 실패 |
INVALID_SUSPENDED_BUSINESS_REGISTRATION_NUMBER | 휴업 사업자번호 |
INVALID_CLOSED_BUSINESS_REGISTRATION_NUMBER | 폐업 사업자번호 |
INVALID_UNREGISTERED_BUSINESS_REGISTRATION_NUMBER | 미등록 사업자 번호 |
NOT_FOUND_KYC_REQUEST_FORM | 신청정보를 찾을 수 없습니다 (상점 신청 정보가 존재하지 않음) |
NOT_FOUND_APPLICANT_CERTIFICATE_INFO | 신청인의 생년월일 및 성별 정보를 찾을 수 없습니다 |
NOT_FOUND_COMPANY_TYPE | 사업자 유형을 찾을 수 없습니다 |
NOT_FOUND_MOBILE_CARRIER | 통신사 정보를 찾을 수 없습니다 |
NOT_FOUND_MERCHANT_ACCOUNT | 상점 정보를 찾을 수 없습니다 |
INVALID_REPRESENTATIVE | 신청인 정보와 대표자 정보가 일치하지 않습니다 |
INVALID_VERIFICATION_INFO | 인증정보가 잘못되었습니다 (통신사에러로 입력정보 불일치(생년월일 유효하지 않음, 휴대폰 앞자리가 이상한, 성명이 비정상)) |
TOO_MANY_IDENTIFY_CERTIFICATION_FAILED | 최대 인증 실패 횟수가 초과되었습니다 (통신사 제한으로 다음날 재시도 가능) |
ALREADY_CONFIRMED_IDENTIFY_CERTIFICATION | 이미 확인된 본인인증 |
INVALID_IDENTIFY_CERTIFICATION_VERIFICATION_CODE | 인증번호가 일치하지 않음 |
INVALID_IDENTIFY_CERTIFICATION_VERIFICATION_TOKEN | 유효하지 않은 본인인증 토큰 |
IDENTIFY_CERTIFICATION_CONFIRM_FAILED | 본인인증 확인에 실패 |