시작하기

구조와 용어

PLATFORM·STORE·거래번호·콜백. 연동 전에 알아야 할 구성 요소와 용어입니다.

구성 요소

귀사 서버 ──(1) 결제 생성 API──▶ 카리페이 게이트웨이 ──(2) 결제 페이지 링크──▶ 귀사 서버
                                        │
고객 ──(3) 링크 접속 · 카드/카카오페이 결제──▶ 결제 페이지(NICE)
                                        │
귀사 CONFIRM_URL ◀──(4) 결제 완료 콜백(POST)── 카리페이 게이트웨이
귀사 서버 ──(5) 조회 API로 승인 상태 이중확인──▶ 카리페이 게이트웨이

청구서 경로에서는 (1)·(2)를 카리페이 청구 서버가 대신 수행하고, 링크를 알림톡/문자로 고객에게 보냅니다.

구성 요소	역할	주소
결제 게이트웨이	결제 생성·조회·취소, 결제 완료 콜백	테스트 `dev-api.chewingpay.com` · 운영 `api.chewingpay.com`
결제 페이지	고객이 카드·카카오페이로 결제하는 화면	`chewingpay.com/payments`
청구 서버	청구서 생성, 알림톡/문자 발송, 수납 상태, 콘솔 백엔드	`api.dev.caripay.co.kr`
공개 청구서 페이지	알림톡·문자 링크가 여는 청구 내역 화면	`caripay.co.kr/pay/{거래번호}`
가맹점 콘솔	청구서 발송·수납·매출 관리 웹	`portal.caripay.co.kr`

용어

용어	설명
`PLATFORM` / `PLATFORM_CODE`	연동 주체(귀사 서비스). API 호출 자격. 서명 시크릿 `API_KEY`가 함께 발급됩니다.
`STORE` / `STORE_CODE`	정산 귀속처(가맹점). 결제대금이 이 가맹점의 정산계좌로 입금됩니다. PG 가맹 정보와 연결됩니다.
`API_KEY`	요청 서명(`API_SIGN`)을 만드는 시크릿. 서버 환경변수·시크릿 매니저에만 보관합니다.
`TRANS_SEQNO`	거래 고유번호. 귀사가 채번하며 전 시스템에서 유일해야 합니다(서비스 접두어 + 시각 + 난수 권장, 최대 64자).
`TRANS_AT`	요청 시각. KST 기준 `yyyyMMddHHmmss` 14자리.
`CONFIRM_URL`	결제 완료 시 카리페이가 POST 하는 귀사 백엔드 URL. 요청마다 지정하며 사전 등록이 없습니다. HTTPS만 허용합니다.
`REDIRECT_URL`	결제 생성 응답으로 받는 고객 결제 페이지 링크.
`APPROVE_STATUS`	거래 상태. `APPROVE_COMPLETE`만 결제 성공입니다. 상태 코드
청구서(Bill)	청구 서버가 관리하는 청구 단위. 상태 `PENDING`(미납) → `DONE`(수납) / `CANCELED`.
발송 수단(`sendChannel`)	청구서 알림을 보내는 수단. `ALIMTALK` · `SMS` · `ALIMTALK_THEN_SMS`.
포인트	청구서 1건 발송(재발송 포함)마다 차감되는 가맹점 발송 포인트.

플랫폼과 가맹점의 관계

자사 서비스(1:1) — PLATFORM 하나에 STORE 하나. 가장 단순합니다.
다중 가맹점 SaaS(1:N) — PLATFORM 하나에 판매자별 STORE. 판매자마다 정산계좌·환불 책임이 분리됩니다. 플랫폼·다중 가맹점
여러 판매자 매출을 솔루션사의 STORE 하나로 모으는 우산 가맹점 구조는 허용하지 않습니다.

거래번호 규칙

게이트웨이 내부 거래 ID는 플랫폼ID_가맹점ID_TRANS_SEQNO로 만들어집니다. 같은 PLATFORM_CODE·STORE_CODE 조합에서 TRANS_SEQNO가 중복되면 4001 이미 처리된 결제요청으로 거절됩니다. SDK의 newTransSeqno("접두어")는 접두어 + 시각 14자리 + 난수를 만듭니다.

문서에 없는 내용이나 오류는 bellight@goatheaven.com 또는 지원 문의로 알려주세요.