> For the complete documentation index, see [llms.txt](https://developers.payssam.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.payssam.kr/api/api-v2/bill.md).
# 청구서
***
## 청구서 발송
> 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\
> sendType에 따라 청구서를 발송합니다.\
> \
> 발송방식 sendType\
> TALK : 생성된 청구서를 결제선생이 발송하는 방식\
> URL : 생성된 청구서의 URL을 전달하는 방식
```json
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill":{"post":{"tags":["청구서 발송/파기"],"summary":" 청구서 발송\n","description":" 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\n sendType에 따라 청구서를 발송합니다.\n\n 발송방식 sendType\n TALK : 생성된 청구서를 결제선생이 발송하는 방식\n URL : 생성된 청구서의 URL을 전달하는 방식\n","operationId":"billSend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResponse"}}}}}}}},"components":{"schemas":{"BillRequest":{"type":"object","description":"청구서 생성 요청 (sendType=TALK: 카카오톡 발송 / sendType=URL: URL만 응답)","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CreateBillInfo"}},"required":["apiKey","member","merchant"]},"CreateBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"sendType":{"type":"string","description":"발송 방식: TALK (카카오톡 발송) 또는 URL (URL만 응답)","enum":["TALK","URL"]},"billIssuer":{"type":"string","description":"청구서 발급처명","maxLength":50,"minLength":0},"productName":{"type":"string","description":"청구 사유","minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"supplyPrice":{"type":"string","description":"공급가액"},"tax":{"type":"string","description":"세액"},"memberName":{"type":"string","description":"고객명","minLength":1},"phone":{"type":"string","description":"고객 전화번호","minLength":1},"message":{"type":"string","description":"안내메세지"},"expireDt":{"type":"string","description":"유효기간 YYYY-MM-DD"},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1},"callbackUrl":{"type":"string","description":"결제 완료 콜백 URL","minLength":1},"pageRedirectUrl":{"type":"string","description":"결제 완료 후 리다이렉트 URL (sendType=URL 인 경우에만 활성화)"}},"required":["billId","callbackUrl","hash","memberName","phone","price","productName","sendType"]},"BaseResponseBillResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResponse","description":"응답 데이터"}}},"BillResponse":{"type":"object","description":"청구서 생성 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"shortUrl":{"type":"string","description":"생성된 청구서 단축 URL"}},"required":["apiKey","member","merchant"]}}}}
```
## 카카오톡 재발송
> 기발송된 청구서를 재발송합니다.\
> 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\
> \
> 사용 시나리오\
> \- 고객이 핸드폰을 분실한경우\
> \- 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우
```json
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/resend":{"post":{"tags":["청구서 발송/파기"],"summary":"카카오톡 재발송","description":" 기발송된 청구서를 재발송합니다.\n 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\n\n 사용 시나리오\n - 고객이 핸드폰을 분실한경우\n - 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우\n","operationId":"billResend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillResendRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResendResponse"}}}}}}}},"components":{"schemas":{"BillResendRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ResendBillInfo"}},"required":["apiKey","member","merchant"]},"ResendBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillResendResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResendResponse","description":"응답 데이터"}}},"BillResendResponse":{"type":"object","description":"카카오톡 청구서 재발송 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"재발송된 청구서 ID"}}}}}}
```
## 청구서 단건 조회
> 발송된 청구서에 대한 결제 상태를 조회합니다.\
> \
> appr\_state : F(결제완료), W(미결제), C(취소), D(파기)\
> 각 상태는 다음과 같이 변경될 수 있습니다.\
> 1\. W(미결제) -> F(결제완료) -> C(취소)\
> 2\. W(미결제) -> D(파기)
```json
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/read":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 단건 조회","description":" 발송된 청구서에 대한 결제 상태를 조회합니다.\n\n appr_state : F(결제완료), W(미결제), C(취소), D(파기)\n 각 상태는 다음과 같이 변경될 수 있습니다.\n 1. W(미결제) -> F(결제완료) -> C(취소)\n 2. W(미결제) -> D(파기)\n","operationId":"billRead","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReadPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillReadPortResponse"}}}}}}}},"components":{"schemas":{"BillReadPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ReadBillInfo"}},"required":["apiKey","member","merchant"]},"ReadBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillReadPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillReadPortResponse","description":"응답 데이터"}}},"BillReadPortResponse":{"type":"object","description":"원장 단건 조회 응답 — v1 SyncVO.Approval 과 동일한 필드 구성","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"청구서 ID"},"apprPayType":{"type":"string","description":"결제수단 코드 (간편결제 0 등)"},"apprCardType":{"type":"string","description":"카드 종류 (신용/체크/정보없음 등)"},"apprDt":{"type":"string","description":"승인 일시 (YYYYMMDDhhmmss)"},"apprOriginDt":{"type":"string","description":"원거래 승인 일시"},"apprPrice":{"type":"string","description":"승인 금액"},"apprIssuer":{"type":"string","description":"카드명 또는 은행명"},"apprIssuerCd":{"type":"string","description":"발행사 코드 또는 은행 코드"},"apprIssuerNum":{"type":"string","description":"카드번호 또는 계좌번호"},"apprAcquirerCd":{"type":"string","description":"매입사 코드"},"apprAcquirerNm":{"type":"string","description":"매입사명"},"apprNum":{"type":"string","description":"승인/취소 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprResCd":{"type":"string","description":"응답 코드"},"apprMonthly":{"type":"string","description":"할부 개월수 (0: 일시불)"},"apprState":{"type":"string","description":"승인 상태 (F:승인, W:대기, C:취소, D:파기)"},"apprCashNum":{"type":"string","description":"현금영수증 승인번호"},"apprCashTrader":{"type":"string","description":"현금영수증 발급 구분"},"apprCashIssuanceNumber":{"type":"string","description":"현금영수증 발급 요청 번호"},"apprCardMerchantNum":{"type":"string","description":"신용카드 가맹점 정보 (헬스케어 스펙)"},"catId":{"type":"string","description":"단말기 번호 (헬스케어 스펙)"},"dscTxNum":{"type":"string","description":"거래 고유번호 (헬스케어 스펙)"},"cardType":{"type":"string","description":"페이민트 공통 카드 타입 (영남대/KOCES 전용)"},"apprSign":{"type":"string","description":"전자서명 데이터 (헬스케어 스펙, Base64)"},"udItem":{"$ref":"#/components/schemas/JsonNode","description":"사용자 정의 항목 (원장 저장 시 전달된 JSON)"}}},"JsonNode":{}}}}
```
## 청구서 파기
> 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\
> 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\
> \
> \- 청구서를 잘못 보낸경우 사용합니다.
```json
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/destroy":{"post":{"tags":["청구서 발송/파기"],"summary":"청구서 파기","description":" 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\n 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\n\n - 청구서를 잘못 보낸경우 사용합니다.\n","operationId":"billDestroy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillDestroyRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillDestroyResponse"}}}}}}}},"components":{"schemas":{"BillDestroyRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/DestroyBillInfo"}},"required":["apiKey","member","merchant"]},"DestroyBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillDestroyResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillDestroyResponse","description":"응답 데이터"}}},"BillDestroyResponse":{"type":"object","description":"청구서 파기 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"파기된 청구서 ID"}}}}}}
```
## 청구서 결제 취소
> 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\
> 결제가 완료되지 않은 청구서는 사용할 수 없습니다.
```json
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/cancel":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 결제 취소","description":" 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\n 결제가 완료되지 않은 청구서는 사용할 수 없습니다.\n","operationId":"billCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCancelPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillCancelPortResponse"}}}}}}}},"components":{"schemas":{"BillCancelPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CancelBillInfo"}},"required":["apiKey","member","merchant"]},"CancelBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"cancelReason":{"type":"string","description":"취소사유","maxLength":20,"minLength":0},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillCancelPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillCancelPortResponse","description":"응답 데이터"}}},"BillCancelPortResponse":{"type":"object","description":"청구서 결제 취소 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"apprNum":{"type":"string","description":"취소 승인 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprCancelDt":{"type":"string","description":"취소 일시 (YYYYMMDDhhmmss)"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers.payssam.kr/api/api-v2/bill.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.