자주 묻는 질문

결제

정기결제(자동결제)가 되나요?

빌링키 자동결제는 지원하지 않습니다. 구독형은 청구서 정기 발송(콘솔 또는 API)으로 매월 청구서를 보내고, 고객이 링크에서 결제하는 방식으로 운영합니다. 금액이 바뀌면 다음 청구서의 금액만 바꾸면 됩니다.

부분 취소(일부 환불)가 되나요?

아니요. CANCEL은 승인금액 전액만 취소됩니다. 일부 환불은 전액 취소 후 새 금액으로 결제를 다시 받거나, 별도 송금으로 처리하세요.

결제 링크에 유효기간이 있나요?

게이트웨이 링크 자체에는 만료가 없습니다. 기한이 지나면 DELETE로 청구를 닫아 결제할 수 없게 하세요. 청구서 API·콘솔은 삭제 기능이 같은 일을 합니다.

결제수단은요?

신용카드와 카카오페이입니다(NICE페이먼츠 인프라). 계좌이체·가상계좌는 현재 지원하지 않습니다.

수수료와 정산 주기는요?

업종·거래 규모에 따라 도입 계약 시 확정합니다. 결제대금은 가맹점(STORE) 정산계좌로 입금되고, 카리페이 이용료는 별도로 청구됩니다.

테스트 환경에서 실제 카드로 결제되나요?

테스트 게이트웨이에서는 실제 카드 결제가 되지 않습니다. 결제 완료 흐름은 거래번호를 알려 주시면 카리페이가 테스트 승인 처리해 드리고, 실제 카드 결제와 취소는 운영 환경에서 소액(100원) 결제 후 전액 취소로 확인합니다.

연동

콜백이 오지 않아요.

CONFIRM_URL이 https://인지, 서버가 2xx를 빠르게 응답하는지, 방화벽이 막지 않는지 확인하세요. 콜백은 실패하면 최대 약 21시간 동안 재시도하지만 늦게 올 수 있으므로, searchPayment 폴링으로 복구하는 경로가 반드시 있어야 합니다.

같은 콜백이 두 번 왔어요.

정상 상황으로 설계돼 있습니다. 이미 처리한 주문이면 200을 응답하고 무시하세요(멱등).

4001 이미 처리된 결제요청이 나요.

같은 TRANS_SEQNO로 다시 생성했습니다. 재시도 로직이 거래번호를 재사용하는지 확인하세요. 이미 만들어진 링크가 있으면 새로 만들지 말고 그 링크를 다시 쓰면 됩니다.

어떤 언어 SDK가 있나요?

Node.js(TypeScript 타입 포함)·Python 공식 SDK가 있고, 그 외 언어는 openapi.yaml로 클라이언트를 생성하거나 서명 규칙대로 직접 호출합니다. 서명은 SHA-256 한 줄입니다.

개인 개발자도 시작할 수 있나요?

공개 SDK·OpenAPI로 연동 코드는 사업자등록 전에도 만들 수 있습니다. 테스트·운영 자격정보는 결제를 받을 사업자와 정산 명의가 정해진 뒤 발급합니다.

청구서·알림톡·문자

알림톡과 문자 중 무엇을 골라야 하나요?

기본은 알림톡입니다. 카카오톡을 쓰지 않거나 채널을 차단한 고객이 섞여 있으면 ALIMTALK_THEN_SMS(알림톡 실패 시 문자)를 기본값으로 두는 것이 가장 도달률이 높습니다. 알림톡을 아예 원치 않는 고객은 SMS.

알림톡 문구를 우리 서비스에 맞게 바꿀 수 있나요?

알림톡은 카카오 심사를 받은 카리페이 범용 청구서 템플릿으로만 나갑니다. 청구 사유·안내 메시지·금액과 청구 항목(상품명·금액 목록)은 자유롭게 넣을 수 있지만 틀 자체는 바꿀 수 없습니다. 발급처·가맹점명은 가맹점 계정의 등록 정보가 들어갑니다. 문자(LMS)는 템플릿 심사가 없어 같은 내용이 자유 형식으로 나갑니다. 청구 항목

발송 비용은요?

청구서 1건 발송(재발송 포함)마다 포인트 1회가 차감됩니다. 문자로 대체되어도 추가 차감은 없습니다. 포인트 단가는 콘솔 포인트 메뉴에서 확인합니다.

고객이 "못 받았다"고 해요.

발송 이력 상태 갱신으로 도착 여부를 확인하고, 실패면 발송 수단을 문자로 바꿔 재발송하세요.

청구서 API에도 웹훅이 있나요?

네. 청구서를 만들 때 webhookUrl을 넣으면 결제 완료(bill.paid)·취소(bill.canceled) 시 POST 합니다. webhookSecret을 함께 주면 X-CariPay-Signature(HMAC-SHA256)로 서명되며 SDK verifyWebhookSignature로 검증합니다. 검증 뒤에도 확정은 getInvoice로 하세요. 결제 완료 웹훅

계정·운영

여러 매장·지점을 운영해요.

지점마다 정산계좌가 다르면 지점별 STORE(가맹점)를 등록합니다. 청구서 API·콘솔은 가맹점 계정 단위라 계정도 분리됩니다.

현금영수증은요?

콘솔의 수납 처리에서 현금·계좌이체 수납 건에 현금영수증을 발급할 수 있습니다. 카드 결제는 카드 매출전표로 대체됩니다.