본 문서는 토스페이 결제 가맹점에서 현금영수증을 발급하거나 취소, 상태 확인 및 현금영수증 이미지 주소를 얻고자 할 때 사용할 API 에 대한 가이드를 제공합니다.
토스페이 결제 가맹점에서는 해당하는 현금영수증 API 를 이용하여 국세청으로 현금영수증을 등록 및 취소, 상태 확인 등을 할 수 있습니다.
이를 위해 토스페이에서는 토스페이먼츠(PG)를 통해 가맹점에게 현금영수증 API 를 제공하고,
토스페이먼츠(PG)를 통해 국세청으로 정상 등록이 되면 통상 2일 안에 국세청으로부터 동기화 과정을 거쳐서 현금영수증의 발급이 완료됩니다.
해당 결제가 status = PAY_COMPLETE 으로 완료되었을 때, 현금 영수증 발급이 가능합니다.
* 주의 사항: 토스의 결제 금액과 현금영수증의 불일치를 막기 위해 - 발급 API 에서는 금액 정보를 파라미터로 받지 않습니다.
이미 결제 처리가 되어 토스 시스템에 기록된 과세 항목, 비과세 항목 등의 값을 바탕으로 현금영수증 발급이 처리됩니다.
| PHONE | 전화번호 |
| CORPORATE | 사업자등록번호 |
| CARD | 카드번호 |
| DEDUCTION | 소득공제용 |
| EVIDENCE | 지출증빙용 |
POST https://pay.toss.im/api/v2/issue-cash-receipt{
"apiKey": "example_api_key",
"payToken": "example_payToken",
"cashReceiptKey": "01001230123",
"cashReceiptKeyType": "PHONE",
"cashReceiptPurpose": "DEDUCTION"
}
{
"status": 200,
"code": 0,
"cashReceiptMgtKey": "123456-123456",
"supplyCost": 909,
"tax": 91,
"serviceFee": 0
}
해당 결제가 status = PAY_COMPLETE 으로 완료되었고, 발급 요청된 현금 영수증이 있을 때에만 호출 가능합니다.
* 주의 사항: 현금영수증 취소 API 의 경우에도 금액과 관련된 parameter 를 받지 않습니다.
결제 환불 API 를 통해 토스 시스템에서 기록된 남은 금액을 바탕으로 현금영수증 취소를 처리합니다.
따라서 전체 환불, 부분 환불의 구분 없이 취소 API 를 호출하면, 남은 결제 금액에 맞게 알아서 처리 됩니다.
POST https://pay.toss.im/api/v2/revoke-cash-receipt{
"apiKey": "example_api_key",
"payToken": "example_payToken"
}
{
"status": 200,
"code": 0,
"cashReceiptMgtKey": "123456-123456",
"supplyCost": 9090,
"tax": 910,
"serviceFee": 0
}
| IN_PROGRESS | 국세청 전송중 |
| ISSUE_APPLIED | 발급 신청 완료 |
| ISSUE_COMPLETE | 발급 완료 |
| ISSUE_FAILED | 발급 실패 |
POST https://pay.toss.im/api/v2/cash-receipt-info{
"apiKey": "example_api_key",
"payToken": "example_payToken"
}
{
"cashReceiptMgtKey": "123456-123456",
"customerName": "김토스",
"itemName": "테스트 상품",
"identityNum": "01012341234",
"taxationType": "과세",
"totalAmount": "10000",
"tradeUsage": "소득공제용",
"tradeType": "승인거래",
"status": "ISSUE_APPLIED",
"tradeDate": "20180512"
}
토스 결제 가맹점을 이용한 고객이 현금영수증의 발급 및 취소된 것의 발급 이미지 등을 요구할 때, 해당 API 를 호출하여 리턴되는 팝업 Uri 값으로 대응이 가능합니다.
POST https://pay.toss.im/api/v2/cash-receipt-popupUri{
"apiKey": "example_api_key",
"payToken": "example_payToken"
}
{
"code": 0,
"popupUri": "https://pay.toss.im/payfront/web/external/cash-receipt?payToken=example_payToken&mgtKey=f017f18b-2356-bNpwieGeQp"
}
✓ 현금영수증 API 를 호출하더라도
1) 국세청으로 전송
2) 국세청에서 확인 후 승인 또는 거절 등의 단계를 거쳐 처리가 되므로, 현금영수증 API 호출 후 통상 2 ~ 3 일의 시일이 지나야 국세청에 등록이 완료됩니다.
✓ 현금영수증 취소의 경우, 환불 시 별도의 원장에 기록된 현금영수증 취소 STANDBY가 환불과 동시에 생성되며 뒷단 배치에서 해당 STANDBY를 읽어 현금영수증 취소 처리 후 토스페이먼츠(PG)로 취소 요청이 전달됩니다.
✓ 토스페이 에러코드는 예고 없이 업데이트 될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.
✓ 토스에서는 한 가지 에러코드에 상황별로 다른 오류 메시지를 전달합니다.
여러 상황이 발생할 수 있으니 되도록이면 전달되는 오류 메시지 그대로를 처리해주세요.
| 응답 코드(errorCode) | 사유(msg) |
| CASH_RECEIPT_JOIN_MEMBER_FAIL | 현금영수증 연동회원 신규가입이 실패하였습니다. |
| CASH_RECEIPT_REGIST_ISSUE_FAIL | 현금영수증을 발행하지 못했습니다. |
| CASH_RECEIPT_ALREADY_ISSUE_FAIL | 현금영수증이 이미 발행 되었습니다. |
| CASH_RECEIPT_ALREADY_CANCEL_FAIL | 현금영수증이 이미 취소 되었습니다. |
| CASH_RECEIPT_ISSUE_IN_PROGRESS | 현금영수증 발행 진행 중 입니다. |
| CASH_RECEIPT_CANCEL_ISSUE_FAIL | 현금영수증 발행 취소를 하지 못했습니다. |
| CASH_RECEIPT_REVOKE_REGIST_ISSUE_FAIL | 취소 현금영수증을 발행하지 못했습니다. |
| CASH_RECEIPT_GET_INFO_FAIL | 현금영수증 정보 확인에 실패하였습니다. |
| CASH_RECEIPT_NOT_EXIST | 발급된 현금영수증이 존재하지 않습니다. |
| CASH_RECEIPT_GET_POPUP_URI_FAIL | 현금영수증 조회 링크를 가져오지 못했습니다. |
| CASH_RECEIPT_UNKNOWN_STATUS_CODE | 존재하지 않는 현금영수증 상태코드 입니다. |
| CASH_RECEIPT_CANNOT_ISSUE_CARD | 카드 결제는 현금영수증을 발행할 수 없습니다. |
| CASH_RECEIPT_MAINTENANCE_TIME | 현금 영수증 서비스 점검 시간입니다. |
| CASH_RECEIPT_INVALID_USER_INFO | 잘못된 식별번호입니다. |
| CASH_RECEIPT_INVALID_PARAMETER | 요청 값이 잘못되었습니다. |
| NOT_SUPPORTED_CASH_RECEIPT_AGENCY | 지원하지 않는 현금영수증 발행처입니다. |