청구서 발송 및 파기

청구서 발송

청구서 발송은 파트너사가 페이민트에 요청하면, 페이민트가 고객에게 카카오 알림톡으로 청구서를 발송하는 구조입니다.

POST /bill

주요 파라미터 안내

파라미터	설명
bill_issuer	청구서에 노출되는 발급처명입니다. 값을 전달하면 해당 값이 노출되고, 미전달 시 사업장명이 기본 노출됩니다.
expire_dt	청구서 유효기간으로 YYYY-MM-DD 형식이며, 입력일 자정까지 유효합니다.
callbackURL	고객 결제 완료 후 승인 결과를 수신할 파트너사 URL입니다. 이 값이 정확하지 않으면 승인동기화를 받을 수 없으므로 반드시 정확히 입력해주세요.

주의사항

• bill_id는 중복 불가합니다. 이미 사용된 bill_id로 발송 요청 시 9800 에러가 반환됩니다.

• hash 값은 phone 유무에 따라 생성 규칙이 달라지므로 반드시 확인해주세요.

• price는 String 타입(최대 10자리)이며, 숫자만 입력합니다.

주의사항

URL 방식에서 자동결제를 사용하는 경우 phone 필드 주의 sendType=URL로 청구서를 발송할 때, phone 필드에 실제 전화번호를 사용하면 동일 가맹점 내 여러 고객의 전화번호가 겹칠 경우 다른 고객의 카드로 자동결제가 처리될 수 있습니다. URL 방식에서 RP를 함께 사용하는 경우, phone 필드에 실제 전화번호 대신 파트너 시스템의 고유 고객 식별자를 넣을 것을 권장합니다. phone 필드는 핸드폰 번호 형식 검증이 없으므로 "user-001", "member_abc" 같은 값을 그대로 사용할 수 있습니다.

청구서 재발송

이미 발송된 청구서를 고객에게 다시 보내는 기능입니다. 청구서 자체는 동일하며, 카카오톡 알림톡이 새로 발송되면서 발송톡(쌤포인트)이 차감됩니다.

POST /bill/resend

사용 시나리오

• 고객이 핸드폰을 분실한 경우

• 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우

주의사항

• 재발송 시에도 쌤포인트가 차감되므로, 불필요한 재발송은 피해야 합니다.

• 기존 bill_id를 그대로 사용해야 합니다.

청구서 파기

결제가 진행되지 않은(미결제 상태인) 청구서를 파기하는 기능입니다.

POST /bill/destroy

주의사항

• 결제가 완료된 청구서는 파기할 수 없습니다. 결제 완료 건은 "결제 취소" API를 사용해야 합니다.

• 파기와 취소는 다른 개념입니다. 파기는 미결제 청구서를 무효화하는 것이고, 취소는 이미 결제된 건을 환불 처리하는 것입니다.

• hash는 {bill_id} + "," + {price} 로 생성합니다.

• 매니저사이트/매니저앱에서 직접 청구서 파기된 경우 API를 통해 callback이 전달되지 않습니다.