변경이력
버전 | 날짜 | 변경사항 |
v202404_1 | 20240429 | 최초작성 |
1. 개요
카페24 샵스 마이그레이션을 위한 API입니다
기존 쇼핑페이 상점의 경우에만 신청할 수 있습니다
2. API 공통사항
2.1. API 인증
호스팅사 → 토스페이먼츠 API 요청 시 인증을 위한 인증 토큰 및 인증 해시를 HTTP 헤더에 포함해야 합니다.
인증 토큰과 비밀키는 호스팅사 단위로 발급되며, 문의시 별도로 전달드립니다.
API Request Header
Name | Type | Description |
Auth-Token | String | API 인증 토큰 |
Auth-Hash | String | Auth-Token, Client Secret, Shop ID를 SHA256으로 Hash |
•
인증 토큰(Auth-Token)은 API를 호출하는 주체를 구분하기 위해 사용됩니다. HTTP 요청 헤더에 Auth-Token으로 항상 공개되어야 합니다.
•
비밀키(Client Secret)는 인증 해시(Auth-Hash)를 생성하는 값의 일부로 사용됩니다.
◦
호스팅사가 생성한 인증 해시를 토스페이먼츠 서버에서 계산하여, 동일한 결과가 나오면 API 요청을 수락하고 요청된 기능을 수행합니다.
◦
만약 비밀키가 유출된 경우 누구나 인증 해시를 생성할 수 있으므로 반드시 토스페이먼츠로 재발급 요청 부탁드립니다.
•
상점 고유 식별자(Shop ID)는 토스페이먼츠가 호스팅사의 상점을 식별하기 위해 사용됩니다. 호스팅사는 반드시 상점 별로 고유한 식별자를 부여하여야 합니다.
•
인증 해시(Auth-Hash)는 API 호출을 인증하기 위해 사용되는 값으로, 인증 토큰, 비밀키, 그리고 상점 고유 식별자를 SHA-256 알고리즘으로 해싱하여 생성합니다. Kotlin 기준 인증 해시 생성 샘플 코드는 다음과 같습니다.
•
샘플코드
fun makeHash(token: String, secret: String, shopId: String) =
MessageDigest.getInstance("SHA-256").also {
it.update(token.toByteArray())
it.update(secret.toByteArray())
it.update(shopId.toByteArray())
}.let {
it.digest().joinToString("") { "%02x".format(it) }
}
Kotlin
복사
public String makeHash (String authToken, String clientSecret, String shopId)
throws NoSuchAlgorithmException {
MessageDigest md = MessageDigest.getInstance( "SHA-256" );
md.update(authToken.getBytes());
md.update(clientSecret.getBytes());
md.update(shopId.getBytes());
return bytesToHex(md.digest());
}
private String bytesToHex ( byte [] bytes) {
StringBuilder builder = new StringBuilder();
for ( byte b : bytes) {
builder.append(String.format( "%02x" , b));
}
return builder.toString();
}
Java
복사
2.2. API 요청
모든 API 요청의 request body 는 application/json 포맷을 수용합니다. 따라서 요청 헤더에 아래의 값이 명시되어야 합니다.
Content-Type: application/json
2.3. API 응답
모든 API 응답은 아래와 같은 구조의 application/json 포맷으로 제공됩니다.
Name | Type | Description |
success | Boolean | API 요청에 대한 성공여부 |
errorCode | String | 요청 처리 과정에서 발생한 에러코드 (성공시 null) |
message | String | 요청 처리 과정에서 발생한 오류메시지 (성공시 null) |
result | JSON | API 응답 별 객체 반환 |
2.4. Base URL
배포 스테이지 별 API 호출 URL은 아래와 같습니다.
Stage | URL |
dev | https://onboarding-api-dev.tosspayments.com |
staging | https://onboarding-api-staging.tosspayments.com |
live | https://onboarding-api.tosspayments.com |
2.5. 접근제한
안전한 서비스 제공을 위해 제한된 환경에서만 통신이 가능합니다.
API 및 페이지에 접근할 호스트를 토스페이먼츠에 별도로 전달 부탁드립니다.
3. 샵스 마이그레이션
3.0. 샵스 마이그레이션 유치코드 정보
agency code = cafe24_sh_m
ㄴ 샵스 마이그레이션용 유치코드
3.1. 마이그레이션 api 호출 (카페24 → 토스페이먼츠)
3.1.1. Request
POST /merchants/api/v1/sub-malls/{businessRegistrationNumber}/merchant-accounts/{salesPartnerSideId}/migration
salesPartnerSideId = 쇼핑페이 위젯상점에서 사용하고 있던 PID 로 보내주세요
Name | Type | Required | Description |
참고용기록 | 대표 MID (PrimeMid)
(샵스의 경우 대표 MID를 환경에따라 토스페이먼츠에서 하기의 대표MID로 강제로 저장하도록 처리함
- 샵스 = CF_cafe24biz5(운영) / CF_cafe24stg4(스테이징)) | ||
newSalesPartnerSideId | String | Y | 신규로 생성할 pid |
salesPartnerCode | String | Y | 유치업체코드 |
business.companyType | String | Y | * CORPORATE(법인사업자)
* PRIVATE(일반사업자)
* NON_PROFIT_CORP(비영리법인)
* NON_PROFIT(공공단체) |
business.companyName | String | Y | 상호명 국문 |
busness.companyEnglishName | String | Y | 상호명 영문 |
business.address.postalCode | String | Y | 사업장 우편번호 |
business.address.main | String | Y | 사업장 주소 |
business.address.detail | String | N | 사업장 상세주소 |
business.companyNationality | CountryCode | Y | 사업장 소재국가 |
business.foundedDate | LocalDate | Y | 회사설립일 |
business.corporateNumber | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 법인번호 |
business.headOfficeAddress.postalCode | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 우편번호 |
business.headOfficeAddress.main | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 주소 |
business.headOfficeAddress.detail | String | N | 본점 상세주소 |
business.headOfficeNationality | CountryCode | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 본점 소재국가 |
business.registeredBusinessType | String | Y | 사업자등록증상 업태 |
business.registeredBusinessItem | String | Y | 사업자등록증상 종목 |
business.taxPayerType | String | Y | 과세유형
* CORPORATE(법인사업자)
* INDIVIDUAL(일반사업자)
* SIMPLIFY(간이사업자과세특례자)
* EXEMPT(면세사업자)
* ETC(기타 비영리단체)
* NONPROFIT(기타후원회)
* NONE(비사업자)
* FOREIGN(해외) |
aml.tradePurpose | String | Y | 거래목적 |
aml.cashSource | String | Y | 자금출처 |
aml.isVirtualCurrency | Boolean | Y | 가상자산사업자여부 |
aml.listedStockMarket | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 상장여부+거래소정보
* HKEX(홍콩증권거래소)
* LSE(런던증권거래소)
* KOSPI(코스피)
* NASDAQ(나스닥)
* KOSDAQ(코스닥)
* NYSE(뉴욕증권거래소)
* ETC(기타)
* NONE(비상장) |
aml.listedStockMarketDescription | String | N
(aml.listedStockMarket이 ETC일 경우 Y) | 상장거래소 정보 기타일시 자유입력텍스트 |
aml.establishmentPurpose | String | N
(비영리법인/단체 일 경우 Y) | 설립목적
* ACADEMIC(학술)
* RELIGION(종교)
* CHARITY(자선)
* CULTURE(문화)
* EDUCATION(교육)
* SOCIAL(사회사업)
* NATION(국가기관 등)
* ETC(기타) |
aml.establishmentPurposeDescription | String | N
(aml.establishmentPurpose이 ETC일 경우 Y) | 설립목적 기타일시 자유입력텍스트 |
aml.largestStakeholderType | String | N
(영리법인, 비영리법인/단체 일 경우 Y) | 실제소유주 구분타입
* OVER_25_STAKE (25%이상 지분소유주)
* LARGEST_AMONG_UNDER_25_STAKE (25%미만이지만 최대지분소유주)
* ELECTED (선임된 대표 또는 이해관계자)
* NOT_LARGEST_BUT_BIG_SHOT (실세)
* NONE (실제소유주=대표자) |
aml.organizationType | String | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 법인/단체 분류
* NATION(국가지방자치단체)
* PUBLIC(공공단체)
* FINANCE(금융회사)
* LISTED(상장사)
* NONE(해당없음) |
aml.isMajorCompany | Boolean | N
(영리법인, 비영리법인/단체, 공공기관, 국가/지방자치단체 일 경우 Y) | 대기업여부 |
representatives[].isPrimary | Boolean | Y | "대표자 주대표자 여부 : 모두가 주대표자일것이기에 true로만 보내주시면됩니다
* >>>>>>공동대표자 정보는 보내지말아주세요<<<<<<<<<<<
*보내주실거면 주대표여부 false 로 해주시고 정보를 보내주세요
(부대표인 경우 거주국가 / 거주지주소 필요없습니다)" |
representatives[].koreanName | String | Y | 대표자 국문명 |
representatives[].englishName | String | Y | 대표자 영문명 |
representatives[].birthDate | String | Y | 대표자 생년월일 (240101 ← 이런형식 YYMMDD) |
representatives[].genderCode | String | Y | 뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기 |
representatives[].nationality | CountryCode | Y | 대표자 국적
2자리 국가코드 (EX:KR) |
representatives[].residenceNationality | CountryCode | N
(주대표자일 경우 Y) | 대표자 거주지 국가 |
representatives[].address.postalCode | String | N
(주대표자일 경우 Y) | 대표자 거주지 우편번호 |
representatives[].address.main | String | N
(주대표자일 경우 Y) | 대표자 거주지 주소 |
representatives[].address.detail | String | N | 대표자 거주지 상세주소 |
representatives[].occupation | Occupation | N
(주대표자일 경우 Y) | 대표자 직업
- 개인사업자일 경우 필수. 여러가지 타입이 있으나 “자영업자"" 고정으로 보내주셔도 무방해요
- 법인사업자일경우 제외
존재하는케이스
* 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 기타 |
actualOwners[].entityType | String | N (실제소유주가 있으면 Y) | 실제소유주 타입
* INDIVIDUAL(개인)
* CORPORATION(법인)
// 법인소유주 케이스가 없다면, 개인소유주 타입 고정으로 보내주셔도 무방합니다 |
actualOwners[].koreanName | String | N (실제소유주가 있으면 Y) | 실제소유주 이름 국문 |
actualOwners[].englishName | String | N (실제소유주가 있으면 Y) | 실제소유주 이름 영문 |
actualOwners[].ratioOfStake | BigDecimal | N (실제소유주가 있으면 Y) | 지분율 (**100을초과할수없습니다) (예시: 33.25, 24, 100) |
actualOwners[].certificateType | String
| N (실제소유주가 있으면 Y) | 실제소유자 증빙서류 유형
* SHAREHOLDERS_LIST (주주명부)
* DART_DOCUMENT (전자공시)
* DART_REPORT (DART 공시자료)
* ARTICLES_OF_ORGANIZATION (정관)
* CORPORATE_REGISTRATION (등기부등본)
* MEETING_MINUTES (회의록)
* OFFICIAL_DOCUMENT (공문)
|
actualOwners[].realOwnerVerificationSkipType | String | N | 실제소유자 생략 시 생략 유형
* FINANCIAL_SERVICES_COMPANY (금융회사)
* GOVERNMENT (국가지방자치단체)
* PUBLIC_ORGANIZATION (공공단체)
* LISTED_COMPANY (상장사)
* NONE (해당없음)
|
actualOwners[].birthDate | String | N
(실소유자가 개인이면 Y) | 실제소유자 생년월일 (240101 ← 이런형식 YYMMDD) |
actualOwners[].genderCode | String | N
(실소유자가 개인이면 Y) | 뒷자리 7자리 중 첫번째 숫자만 보내주세요
1 2 3 4 5 6 7 8 <- 중 하나
기존 2000000<- 이런형식 X : 2만 보내기 |
actualOwners[].nationality | CountryCode | N
(실소유자가 개인이면 Y) | 개인인 경우 : 실제소유주 국적
법인인 경우 : 사업장 소재지국적 |
actualOwners[].residenceNationality | CountryCode | N
(실소유자가 개인이면 Y) | 카페24에서는 수집하지 않는 정보로 알고있습니다.
- nationality 랑 똑같은 값으로 보내주세요 |
actualOwners[].foundedDate | LocalDate | N
(실소유자가 법인이면 Y) | 법인 설립일자 |
actualOwners[].organizationType | String | N
(실소유자가 법인이면 Y) | 실제소유자 법인 분류
* NATION(국가지방자치단체)
* PUBLIC(공공단체)
* FINANCE(금융회사)
* LISTED(상장사)
* NONE(해당없음) |
homepageUrl | String | Y | 상점 대표URL |
phoneNumber | String | Y | 상점 대표전화번호 |
bankAccount.bank | String | Y | 가맹점 정산계좌 은행코드
금융결제원 [대표코드 및 기관코드] 참조 https://www.kftc.or.kr/kftc/data/EgovBankList.do |
bankAccount.bankAccountNumber | String | Y | 가맹점 정산계좌 계좌번호 |
bankAccount.holderName | String | Y | 가맹점 정산계좌 예금주 |
attachments[].type | String | Y | 상점단위 첨부 서류 종류
사업자 단위 첨부 서류 종류
* COMPANY_REGISTRATION (사업자등록증 또는 고유번호증)
* CORPORATE_REGISTRATION (법인등기부등본)
* COPY_OF_BANK_ACCOUNT (통장사본)
* 대표자_신분증 (대표자 신분증)
* SHAREHOLDER (주주명부)
* 추가_보완_서류 (사업자 단위 추가 서류)
상점 단위 첨부 서류 종류
* CO_REPRESENTATIVE_WARRANT (공동대표자 위임장)
* CO_REPRESENTATIVE_SIGNATURE (공동대표자 인감증명서)
* 상점_단위_추가_보완_서류 (상점 단위 추가서류)
//특이사항 기록
// 6월 초 정보업데이트 API배포시점에 아래와같이 한글이넘으로 교체될 예정
사업자 단위 첨부 서류 종류
* 사업자등록증_또는_고유번호증 (사업자등록증 또는 고유번호증)
* 법인등기사항전부증명서 (법인등기부등본)
* COPY_OF_BANK_ACCOUNT (통장사본)
* 대표자_신분증 (대표자 신분증)
* 주주명부 (주주명부)
* 추가_보완_서류 (사업자 단위 추가 서류)
상점 단위 첨부 서류 종류
* 공동_대표자_위임장 (공동대표자 위임장)
* 공동_대표자_인감증명서 (공동대표자 인감증명서)
* 상점_단위_추가_보완_서류 (상점 단위 추가서류) |
attachments[].url | String | Y | 첨부파일 url
※ 200자 내의 url만 허용(200자 제한) |
applicant.name | String | Y | 신청자 이름 |
applicant.email | String | Y | 신청자 이메일 |
applicant.phoneNumber | String | Y | 신청자 연락처 |
3.1.2. Response
Name | Type | Description |
salesPartnerSideId | String | 상점 고유 식별자(pid) |
mid | String | 결제창 호출에 사용할 상점아이디(MID) |
mertKey | String | 결제창 호출에 사용할 머트키 |
clientKey | String | 결제창 호출에 사용할 라이브 클라이언트 키 |
secretKey | String | 결제창 호출에 사용할 라이브 시크릿 키 |