현금영수증 발급 및 취소하기
홈택스 접속 없이 토스페이먼츠에서 제공하는 현금영수증 API로 현금영수증을 편리하게 발급해보세요. 토스페이먼츠에서는 발급 요청된 현금영수증을 모아 국세청에 전달합니다. 토스페이먼츠로 결제하지 않은 건에 대해서도 발급 및 취소 요청을 할 수 있습니다.
고객이 가상계좌나 계좌이체와 같이 현금성 결제 수단으로 결제했다면, 고객이 현금영수증 발급을 신청하지 않았거나 발행을 원하지 않더라도 현금영수증 발급의무에 따라 상점에서 현금영수증을 발행해야 합니다.
현금영수증 발급하기
현금영수증을 발급할 때는 결제 정보 외에도 꼭 필요한 정보가 있습니다. 현금영수증 발급 용도와 현금영수증 발급에 필요한 개인 식별 번호입니다.
현금영수증 발급 용도는 개인 소득 공제와 사업자 지출 증빙으로 나뉩니다. 소득 공제를 위해 현금영수증을 발급받을 때는 개인 식별 번호로 휴대폰 번호나 주민등록번호가 필요하고, 지출 증빙을 위해 현금영수증을 발급받을 때는 사업자 등록번호를 입력해야 합니다.
현금영수증 발급 API를 요청할 때도 이 정보를 파라미터로 보내줘야 합니다. 요청 본문에 현금영수증 발급 용도를 type에 추가하고, 개인 식별 번호는 customerIdentityNumber에 추가해주세요.
아래 예시에서는 결제 고객의 소득공제를 위해 현금영수증을 발급하기 때문에 type 값으로 소득공제를 추가하고 customerIdentityNumber 값으로는 고객의 휴대폰 번호를 입력했습니다.
curl --request POST \
--url https://api.tosspayments.com/v1/cash-receipts \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"orderId":"XLXzXYdaLcASBrjRF_PzT","orderName":"토스 티셔츠 외 2건","amount":"10000","type":"소득공제","customerIdentityNumber":"01012345678"}'만약 하나의 결제에 과세 상품과 면세 상품이 섞여있다면 taxFreeAmount 파라미터를 추가해서 면세 상품 금액을 보내주세요. 보낸 금액 만큼 현금영수증이 발급됩니다. 면세 금액 처리에 대한 좀 더 자세한 설명은 세금 처리하기에서 확인할 수 있습니다.
결제 고객의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다.
API 요청에 대한 응답은 아래와 같이 돌아옵니다.
{
"receiptKey": "aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
"orderId": "",
"orderName": "토스티셔츠 외 2건",
"type": "소득공제",
"issueNumber": "160594074",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
"businessNumber": "1111111111",
"transactionType": "CONFIRM",
"amount": 10000,
"taxFreeAmount": 909,
"issueStatus": "IN_PROGRESS",
"failure": null,
"requestedAt": "2022-07-27T22:39:19+09:00",
"customerIdentityNumber": "01000001234"
}
응답 객체의 transactionType을 통해 이 요청이 현금영수증을 발급하는 요청(CONFIRM)인지, 발급한 현금영수증을 취소하는 요청(CANCEL)인지 알 수 있습니다.
issueStatus는 현금영수증 발급 및 발급 취소 요청 상태를 나타냅니다. 응답이 돌아왔을 때 상태는 IN_PROGRESS로, 토스페이먼츠에 요청이 전달만 된 상태이고, 아직 국세청에 요청이 넘어가기 전입니다. 전달된 요청 건들을 토스페이먼츠에서 다음 날 오후에 일괄적으로 국세청에 전송합니다. 이 때 상태가 SENT로 변경됩니다.
현금영수증 발급 취소하기
현금영수증을 발급한 결제가 취소됐을 때 현금영수증도 취소하기 위해 사용합니다. 현금영수증 발급 API의 응답으로 받았던 receiptKey를 저장하고 있다가 Path 파라미터로 추가하세요.
부분 취소가 된 경우에는 amount 값에 취소된 금액을 입력해서 사용합니다. amount 값이 없으면 전액 취소됩니다.
취소가 정상적으로 되면 응답에 canceledAt 값이 포함되어 돌아옵니다.
{
"receiptKey": "c_aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
"orderId": "oid-220728",
"orderName": "",
"type": "소득공제",
"issueNumber": "160592932",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
"businessNumber": "1111111111",
"transactionType": "CANCEL",
"amount": 5000,
"taxFreeAmount": 455,
"issueStatus": "IN_PROGRESS",
"failure": null,
"requestedAt": "2022-07-27T22:40:13+09:00",
"customerIdentityNumber": "01000001234"
}