하위사업자 등록
차액정산을 요청하기 위해서는 하위사업자 정보가 카드사에 등록되어야 합니다. 하위사업자 등록 API를 통해 하위사업자 정보를 카드사에 전송해 차액정산을 받을 수 있도록 기록합니다.
하위사업자 등록 요청과 결과 조회는 파일형태로 이루어집니다. 하위사업자 등록 및 결과 조회 과정에서는 암복호화가 필수로 요구됩니다.
Interface 정의
하위사업자 등록 요청 및 결과 조회를 위해 사용되는 파일 형태입니다. 하위사업자 파일은 아래 안내되는 전문 string이 이어져 있는 하나의 파일 구조입니다.
하위사업자 등록 요청 파일은 start record + data record + end record로 구성되어 있습니다.
start record string
등록의 주체가 되는 가맹점의 사업자번호와 PG사 구분 코드가 들어갑니다.
500 byte 제한이 있습니다.
data record string
등록하는 하위몰 개수에 따라 가변하는 영역으로, 하위몰의 세부 정보가 기록됩니다.
1개 하위몰 마다 500 byte 제한이 있습니다.
end record string
전송된 전체 하위몰 개수를 나타내는 영역입니다.
500 byte 제한이 있습니다.
하위사업자 등록하기
POST /cl/open/noregrequest.do
하위사업자 등록 API 호출을 통해 요청 파일을 업로드하는 방식으로 등록이 이루어집니다. 접수 마감시간은 매일 오전 03:00이며, 동일한 파일로 재요청하는 경우에는 기존 파일이 덮어씌워집니다.
만약 하나의 파일에 포함된 data record가 너무 길다면, 여러개의 파일로 분할해서 전송이 가능하며, 이 경우 각각의 파일마다 start record와 end record가 존재해야 합니다. 다만 파일을 2개 이상으로 보낸다면 사전에 토스페이먼츠와 협의가 필요하며, 일정 간격을 두고 순차적으로 파일을 업로드해야 합니다.
하위사업자 등록 요청용 파일명은 사전에 토스페이먼츠와 협의를 통해 정의가 필요합니다.
하위사업자 등록 요청 중 오류가 발생해 실패한 오류건은 다음날 전달되는 파일에 포함해서 다시 전송해야 합니다.
파일 파라미터
type=”file”
name=”reqfile” 필수 · string
차액정산 한 건을 특정할 수 있도록 상점에서 직접 설정한 ID입니다.
전문 표기 형식
아래 전문 record에서 표기되는 형식과 padding, 정렬방식은 다음과 같습니다:
전문표기형식 | A | N | S | H |
정렬 | 왼쪽 | 오른쪽 | 왼쪽 | 왼쪽 |
padding | 공백 | 0 | 공백 | 공백 |
•
모든 레코드의 끝은 CR-LF 로 처리해야합니다.
start record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“01” 고정 값입니다.
파일생성일 필수 · string
•
길이: 8 byte
•
전문표기형식: N
•
파일 생성일자로, yyyyMMdd 형식입니다.
사업자번호 필수 · string
•
길이: 10 byte
•
전문표기형식: N
•
하위사업자 등록의 주체가 되는 2차 PG사의 사업자번호입니다.
PG사구분코드 필수 · string
•
길이: 10 byte
•
전문표기형식: A
•
“TossPaymen” 값이 고정으로 들어갑니다.
filler 필수 · string
•
길이: 470 byte
•
전문표기형식: A
•
공백으로 존재합니다.
data record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“11” 고정 값입니다.
등록구분 필수 · string
•
길이: 2 byte
•
전문표기형식: N
•
하위몰의 상태를 나타냅니다.
◦
00: 신규 상점
◦
01: 해지 상점
•
변경이 필요한 경우 01로 해지 후 00 신규로 다시 처리합니다.
카드사 구분 필수 · string
•
길이: 3 byte
•
전문표기형식: N
◦
016:국민
◦
018:농협
◦
026:비씨
◦
027:현대
◦
029:신한
◦
006:하나
◦
047:롯데
◦
031:삼성
◦
036:우리
하위몰 사업자번호 필수 · string
•
길이: 10 byte
•
전문표기형식: AN
•
차액정산 요청의 대상이 되는 하위몰 사업자번호 입니다.
하위몰 업종명 · string
•
길이: 20 byte
•
전문표기형식: HS
•
특수기호를 포함해 한글 10자까지 입력 가능합니다.
하위몰 회사명 필수 · string
•
길이: 40 byte
•
전문표기형식: ANHS
•
특수기호를 포함해 한글 20자까지 입력 가능합니다.
하위몰 웹사이트 필수 · string
•
길이: 80 byte
•
전문표기형식: ANS
하위몰 주소 · string
•
길이: 100 byte
•
전문표기형식: HS
하위몰 대표자명 · string
•
길이: 40 byte
•
전문표기형식: H
하위몰 전화번호 필수 · string
•
길이: 11 byte
•
전문표기형식: AN
하위몰 이메일 · string
•
길이: 40 byte
•
전문표기형식: ANS
하위몰 정보 등록일 필수 · string
•
길이: 8 byte
•
전문표기형식: N
•
2차 PG에 해당 하위몰이 등록된 일자로, yyyyMMdd 형식입니다.
가맹점예약필드 · string
•
길이: 40 byte
•
전문표기형식: AN
filler 필수 · string
•
길이: 104 byte
•
전문표기형식: A
•
공백으로 존재합니다.
end record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“02” 고정 값입니다.
전체전송건수 필수 · string
•
길이: 10 byte
•
전문표기형식: N
•
등록 요청한 전체 하위몰의 수입니다.
filler 필수 · string
•
길이: 488 byte
•
전문표기형식: A
•
공백으로 존재합니다.
요청 파일 예시
01202401020123456789TossPaymen
11000161058123434통신판매업 갑을상사 주식회사
(data record 반복....)
020000000032
<EOF>
Shell
복사
하위사업자 결과 조회하기
POST /cl/open/noregrequest.do
하위사업자 등록 결과 파일은 매일 오전 07:00에 생성됩니다.
처리 결과 중 반송코드 00:정상처리, 12:하위몰 기등재 를 제외한 모든 반송건은 데이터 수정 후 재전송해야 하위사업자 등록이 처리됩니다.
파일 파라미터
type=”file”
name=”reqfile” 필수 · string
차액정산 한 건을 특정할 수 있도록 상점에서 직접 설정한 ID입니다.
전문 표기 형식
아래 전문 record에서 표기되는 형식과 padding, 정렬방식은 다음과 같습니다:
전문표기형식 | A | N | S | H |
정렬 | 왼쪽 | 오른쪽 | 왼쪽 | 왼쪽 |
padding | 공백 | 0 | 공백 | 공백 |
•
모든 레코드의 끝은 CR-LF 로 처리해야합니다.
start record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“01” 고정 값입니다.
파일생성일 필수 · string
•
길이: 8 byte
•
전문표기형식: N
•
파일 생성일자로, yyyyMMdd 형식입니다.
사업자번호 필수 · string
•
길이: 10 byte
•
전문표기형식: N
•
하위사업자 등록의 주체가 되는 2차 PG사의 사업자번호입니다.
PG사구분코드 필수 · string
•
길이: 10 byte
•
전문표기형식: A
•
“TossPaymen” 값이 고정으로 들어갑니다.
filler 필수 · string
•
길이: 470 byte
•
전문표기형식: A
•
공백으로 존재합니다.
data record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“11” 고정 값입니다.
등록구분 필수 · string
•
길이: 2 byte
•
전문표기형식: N
•
하위몰의 상태를 나타냅니다.
◦
00: 신규 상점
◦
01: 해지 상점
•
변경이 필요한 경우 01로 해지 후 00 신규로 다시 처리합니다.
카드사 구분 필수 · string
•
길이: 3 byte
•
전문표기형식: N
◦
016:국민
◦
018:농협
◦
026:비씨
◦
027:현대
◦
029:신한
◦
006:하나
◦
047:롯데
◦
031:삼성
◦
036:우리
하위몰 사업자번호 필수 · string
•
길이: 10 byte
•
전문표기형식: AN
•
차액정산 요청의 대상이 되는 하위몰 사업자번호 입니다.
하위몰 업종명 · string
•
길이: 20 byte
•
전문표기형식: HS
•
특수기호를 포함해 한글 10자까지 입력 가능합니다.
하위몰 회사명 필수 · string
•
길이: 40 byte
•
전문표기형식: ANHS
•
특수기호를 포함해 한글 20자까지 입력 가능합니다.
하위몰 웹사이트 필수 · string
•
길이: 80 byte
•
전문표기형식: ANS
하위몰 주소 · string
•
길이: 100 byte
•
전문표기형식: HS
하위몰 대표자명 · string
•
길이: 40 byte
•
전문표기형식: H
하위몰 전화번호 필수 · string
•
길이: 11 byte
•
전문표기형식: AN
하위몰 이메일 · string
•
길이: 40 byte
•
전문표기형식: ANS
하위몰 정보 등록일 필수 · string
•
길이: 8 byte
•
전문표기형식: N
•
2차 PG에 해당 하위몰이 등록된 일자로, yyyyMMdd 형식입니다.
반송(결과)코드 · string
•
길이: 2 byte
•
전문표기형식: N
•
자세한 결과에 대한 설명은 [카드사 별 반송 코드]를 참고하세요.
가맹점예약필드 · string
•
길이: 40 byte
•
전문표기형식: AN
filler 필수 · string
•
길이: 104 byte
•
전문표기형식: A
•
공백으로 존재합니다.
end record
레코드구분 필수 · string
•
길이: 2 byte
•
전문표기형식: AN
•
“02” 고정 값입니다.
전체전송건수 필수 · string
•
길이: 10 byte
•
전문표기형식: N
•
등록 요청한 전체 하위몰의 수입니다.
filler 필수 · string
•
길이: 488 byte
•
전문표기형식: A
•
공백으로 존재합니다.
요청 파일 예시
01202401020123456789TossPaymen
11000161058123434통신판매업 갑을상사 주식회사
(data record 반복....)
020000000032
<EOF>
Shell
복사
카드사 별 반송 코드
카드사 | 반송코드 | 반송사유 |
국민 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | 회사명 오류 | |
03 | 사업자등록번호(PG) 오류 | |
04 | 가맹점번호 오류 | |
05 | 사업자번호(하위몰) 오류 | |
06 | 필수값 누락(회사명) | |
07 | 필수값 누락(URL) | |
08 | 필수값 누락(전화번호) | |
11 | 사업자등록번호(PG) 1차 하위몰 미등재 | |
12 | 기등재(1차 하위몰) | |
99 | 기타 | |
농협 | 00 | 정상처리 |
01 | 레코드구분 오류 | |
02 | 등록구분 오류 | |
03 | VAN기관코드 오류 | |
04 | 사업자등록번호(PG) 오류 | |
05 | 가맹점번호 오류 | |
06 | 사업자번호(하위몰) 오류 | |
07 | 회사명 오류 ( 필수 및 정합성 ) | |
08 | URL 오류 ( 필수 및 정합성 ) | |
09 | 전화번호 오류 ( 필수 및 정합성 ) | |
10 | 정보등록일 오류 | |
11 | 등록구분 01, 02인 경우 하위몰 미등재 | |
12 | 등록구분 00인 경우 하위몰 기등재 | |
13 | 총건수 오류 | |
99 | 기타 | |
현대 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | VAN 기관코드 오류 | |
03 | 사업자등록번호(PG) 오류 | |
04 | 사업자번호(하위몰) 오류 | |
05 | 회사명(하위몰) 누락 | |
06 | 웹사이트 URL(하위몰) 누락 | |
07 | 전화번호(하위몰) 누락 | |
08 | 정보등록일 오류 | |
09 | 등록구분 01,02인 경우 하위몰 미등재 | |
10 | 등록구분 00인 경우 하위몰 기등재 | |
99 | 기타 | |
하나 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | 회사명 오류 | |
03 | 사업자등록번호(PG) 오류 | |
04 | 가맹점번호 오류 | |
05 | 사업자번호(하위몰) 오류 | |
06 | 필수값 누락(회사명) | |
07 | 필수값 누락(URL) | |
08 | 필수값 누락(전화번호) | |
11 | 사업자등록번호(PG) 1차 하위몰 미등재 | |
12 | 기등재(1차 하위몰) | |
99 | 기타 | |
신한 | 00 | 정상처리 |
01 | 등록구분 오류(등록구분 00,01,02 이외의 경우) | |
02 | 사업자등록번호(PG) 오류(자리수(10자리)확인) | |
03 | 사업자번호(하위몰) 오류(자리수(10자리)확인) | |
04 | 회사명 오류(자리수 초과 등) | |
05 | 전화번호 오류(자리수 초과 등) | |
06 | 대표자명(하위몰)(자리수 초과 등) | |
07 | 등록구분 01, 02인 경우 하위몰 미등재(등록구분 01,02이나 기존 대상이 없는 경우) | |
99 | 기타 | |
롯데 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | 회사명 오류 | |
03 | 사업자등록번호(PG) 오류 | |
04 | 가맹점번호 오류 | |
05 | 사업자번호(하위몰) 오류 | |
06 | 필수값 누락(회사명) | |
07 | 필수값 누락(URL) | |
08 | 필수값 누락(전화번호) | |
11 | 등록코드 01인 경우 하위몰 미등재 | |
99 | 기타 | |
우리 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | VAN기관코드 오류 | |
03 | 사업자등록번호(PG) 오류 | |
04 | 사업자등록번호(하위몰) 오류 | |
05 | 회사명(하위몰) 오류 | |
06 | 웹사이트URL(하위몰) 오류 | |
07 | 전화번호(하위몰) 누락 | |
08 | 정보등록일 오류 | |
09 | 사업자등록번호(PG) 1차 하위몰 미등재 | |
10 | 기등재(1차 하위몰) | |
99 | 기타 | |
비씨
2023.04.11추가 | 00 | 정상처리 |
01 | 등록구분 오류 | |
02 | PG 사업자번호오류 | |
03 | PG사 코드 오류 | |
04 | 비씨 미존재 PG 사업자 | |
05 | 서브몰 사업자번호 오류 | |
06 | 서브몰 전화번호 오류 | |
07 | 유효한 기등록번호 미존재 | |
99 | 기타 오류 |
삼성카드는 카드사에서 하위사업자 등록 결과를 전달하지 않습니다.
요청시에는 9개 카드사 모두 하위몰 등록 요청이 필요하며, 타 카드사에서 정상응답을 받았다면 정상등록 된것으로 처리하면 됩니다.
타 카드사에서 오류를 받았다면 정보를 수정하여 삼성카드도 함께 9개 카드사 모두 재요청이 필요합니다.