현금영수증 단건 조회
GET /v2/cash-receipts/{id} 로 현금영수증 하나의 발급 상태, 금액 구성, 실패 사유, 취소 내역을 조회해요.
GET /v2/cash-receipts/{id}
현금영수증 ID로 현금영수증 하나를 조회해요. 발급을 요청한 직후에는 status가 PENDING이에요. 국세청 처리 결과는 보통 다음 날 와요. 짧은 간격으로 계속 조회하지 말고 시간을 두고 확인하세요.
경로 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
id |
string | 조회할 현금영수증 ID예요. crt_로 시작해요. |
요청 예시
curl https://api.paysync.kr/v2/cash-receipts/crt_a1b2c3d4e5f6g7h8i9j0k1l2 \
-H "Authorization: Bearer $PAYSYNC_API_KEY"const res = await fetch(`https://api.paysync.kr/v2/cash-receipts/${cashReceiptId}`, {
headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { code, data } = await res.json();import os
import requests
res = requests.get(
f"https://api.paysync.kr/v2/cash-receipts/{cash_receipt_id}",
headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
)
print(res.json())응답
{
"code": "10001",
"data": {
"id": "crt_a1b2c3d4e5f6g7h8i9j0k1l2",
"kind": "ORIGINAL",
"status": "ISSUED",
"type": "PERSONAL",
"identifier": "01012345678",
"selfIssued": false,
"customerName": "홍길동",
"amount": 50000,
"supplyCost": 45455,
"tax": 4545,
"serviceFee": 0,
"taxation": "TAXABLE",
"itemName": "페이싱크상점 주문 #1043",
"method": "AUTO",
"invoiceId": "ivc_n0o1p2q3r4s5t6u7v8w9x0y1",
"invoiceNumber": 1043,
"ntsConfirmNum": "TB0000123",
"tradeDate": "20260428",
"failure": null,
"ntsSentAt": 1777420800,
"ntsResultAt": 1777424400,
"ntsResultCode": "0000",
"originalId": null,
"cancellationIds": [],
"canceledAmount": 0,
"remainingAmount": 50000,
"partial": false,
"reissuedFromId": null,
"reissuedToId": null,
"cancelReason": null,
"issuedBy": { "type": "SYSTEM", "accountId": null, "apiKeyId": null, "name": null },
"createdAt": 1777346413,
"updatedAt": 1777424400,
"canceledAt": null
}
}
현금영수증 객체
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string | 현금영수증 ID예요. crt_로 시작해요. |
kind |
string | ORIGINAL(발급) 또는 CANCELLATION(취소 영수증)이에요. |
status |
string | 발급 상태예요. 아래 표를 참고하세요. |
type |
string | PERSONAL(소득공제용) 또는 CORPORATE(지출증빙용)예요. |
identifier |
string | 휴대폰 번호, 현금영수증 카드 번호, 사업자등록번호예요. 가리지 않고 그대로 와요. |
selfIssued |
boolean | 자진발급이면 true예요. 이때 identifier는 0100001234예요. |
customerName |
string | null | 구매자 이름이에요. |
amount |
integer | 거래 금액(원)이에요. 부가세를 포함해요. |
supplyCost |
integer | 공급가액이에요. |
tax |
integer | 부가세예요. 면세면 0이에요. |
serviceFee |
integer | 봉사료예요. 항상 0이에요. |
taxation |
string | TAXABLE(과세) 또는 TAX_FREE(면세)예요. |
itemName |
string | null | 국세청에 신고한 품목명이에요. |
method |
string | AUTO(주문 결제 완료로 자동 발급) 또는 MANUAL(대시보드나 API로 직접 발급)이에요. |
invoiceId |
string | null | 연결된 주문 ID예요. |
invoiceNumber |
integer | null | 연결된 주문번호예요. |
ntsConfirmNum |
string | null | 국세청 승인번호예요. 발급 요청이 접수되면 받아요. |
tradeDate |
string | null | 거래일자예요. YYYYMMDD 형식이에요. |
failure |
object | null | 발급에 실패한 이유예요. 아래 표를 참고하세요. |
ntsSentAt |
integer | null | 국세청에 전송한 시각이에요. |
ntsResultAt |
integer | null | 국세청 처리 결과를 받은 시각이에요. |
ntsResultCode |
string | null | 국세청 처리 결과 코드예요. |
originalId |
string | null | 취소 영수증이면 원본 현금영수증 ID예요. |
cancellationIds |
string[] | 원본이면 이 현금영수증을 취소한 취소 영수증 ID 목록이에요. |
canceledAmount |
integer | 지금까지 취소한 금액이에요. |
remainingAmount |
integer | 더 취소할 수 있는 금액이에요. |
partial |
boolean | 취소 영수증이 원본 금액의 일부만 취소했으면 true예요. |
reissuedFromId |
string | null | 재발급으로 만든 현금영수증이면 실패한 원본 ID예요. |
reissuedToId |
string | null | 재발급했다면 새 현금영수증 ID예요. |
cancelReason |
string | null | 취소 영수증의 취소 사유예요. |
issuedBy |
object | 발급한 주체예요. 형식은 주체 객체와 같아요. |
createdAt |
integer | 발급을 요청한 시각이에요. |
updatedAt |
integer | null | 마지막으로 바뀐 시각이에요. |
canceledAt |
integer | null | 원본 금액 전체가 취소된 시각이에요. |
발급 상태
status |
뜻 |
|---|---|
PENDING |
팝빌이 요청을 받았고 국세청 처리를 기다려요. 이 상태에서는 취소할 수 없어요. |
ISSUED |
국세청 처리가 끝나 발급됐어요. 취소할 수 있어요. 일부만 취소한 원본도 ISSUED예요. |
FAILED |
팝빌이나 국세청이 발급을 거절했어요. failure로 이유를 확인하고 재발급하세요. |
CANCELED |
원본 금액 전체를 취소했어요. |
failure 객체
| 필드 | 타입 | 설명 |
|---|---|---|
stage |
string | REQUEST(팝빌이 요청을 거절) 또는 NTS(국세청이 거절)예요. |
code |
string | 팝빌 오류 코드나 국세청 결과 코드예요. |
message |
string | 실패 사유예요. |
action |
string | 해결 방법이에요. FIX_IDENTIFIER(식별번호를 고쳐 재발급), CHECK_BUSINESS_INFO(사업자 정보 확인), CONTACT_SUPPORT(문의) 중 하나예요. |
오류
| HTTP | code |
발생 조건 |
|---|---|---|
| 401 | 290006 |
API 키가 올바르지 않아요. |
| 404 | 20015 |
현금영수증이 없어요. |
| 422 | 240001 |
현금영수증 ID 형식이 틀렸어요. |