본문으로 건너뛰기
페이싱크 개발자센터
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

현금영수증 발급

POST /v2/cash-receipts 로 현금영수증 발급을 요청해요. 주문과 연결하거나 자진발급할 수 있어요.

POST /v2/cash-receipts

현금영수증 발급을 요청해요. 주문이 결제 완료될 때 자동으로 발급하려면 이 API 대신 주문 생성에서 cashReceipt를 넣으세요.

발급 요청은 현금영수증 발급 대행사(팝빌)를 거쳐 국세청으로 가요. 팝빌이 요청을 받으면 status가 PENDING이고, 국세청 처리 결과가 오면 ISSUED나 FAILED로 바뀌어요. 결과는 현금영수증 단건 조회로 확인하세요.

요청 본문

필드 타입 필수 설명
type string 예 PERSONAL(소득공제용) 또는 CORPORATE(지출증빙용)예요.
identifier string PERSONAL이면 휴대폰 번호나 현금영수증 카드 번호(숫자 10~18자리), CORPORATE이면 사업자등록번호(숫자 10자리)예요. 하이픈과 공백은 빼고 검사해요. selfIssued가 true가 아니면 필수예요.
selfIssued boolean true면 자진발급해요. 기본값은 false예요.
amount integer 예 부가세를 포함한 거래 금액(원)이에요. 1원부터 999,999,999원까지예요.
customerName string 구매자 이름이에요. 40자까지예요.
invoiceId string 연결할 주문 ID예요. 주문번호가 품목명에 들어가요. 주문에 구매자 이메일이 있고 발급 설정의 발급 알림 메일이 켜져 있으면 발급 안내 메일을 보내요.

과세 유형과 품목명은 대시보드 현금영수증 > 발급 설정을 따라요. 과세면 부가세는 amount의 11분의 1을 반올림한 값이고, 면세면 amount 전체가 공급가액이에요.

한 주문에는 발급했거나 발급 중인 원본 현금영수증을 하나만 둘 수 있어요. 이미 있으면 240012와 함께 그 현금영수증 ID가 와요.

자진발급

구매자가 식별번호를 주지 않은 현금 거래는 국세청 지정 번호 010-000-1234로 소득공제용 현금영수증을 발급할 수 있어요. selfIssued를 true로 보내면 type은 PERSONAL이어야 하고, identifier는 무시해요.

대시보드 현금영수증 > 발급 설정에서 자진발급을 켜면, cashReceipt 없이 결제 완료된 주문 중 기준 금액 이상인 주문을 자동으로 자진발급해요. 기준 금액의 기본값은 현금영수증 의무발행 기준인 100,000원이에요.

발급이 거절됐을 때

팝빌이 요청을 거절해도 HTTP 200과 함께 status가 FAILED인 현금영수증이 와요. failure에서 이유와 해결 방법을 확인하고, 식별번호를 고쳐야 한다면 재발급하세요.

요청 예시

curl -X POST https://api.paysync.kr/v2/cash-receipts \
  -H "Authorization: Bearer $PAYSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PERSONAL",
    "identifier": "01012345678",
    "amount": 50000,
    "customerName": "홍길동",
    "invoiceId": "ivc_n0o1p2q3r4s5t6u7v8w9x0y1"
  }'
const res = await fetch("https://api.paysync.kr/v2/cash-receipts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "PERSONAL",
    identifier: "01012345678",
    amount: 50000,
    customerName: "홍길동",
    invoiceId: "ivc_n0o1p2q3r4s5t6u7v8w9x0y1",
  }),
});
const { code, data } = await res.json();
import os
import requests

res = requests.post(
    "https://api.paysync.kr/v2/cash-receipts",
    headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
    json={
        "type": "PERSONAL",
        "identifier": "01012345678",
        "amount": 50000,
        "customerName": "홍길동",
        "invoiceId": "ivc_n0o1p2q3r4s5t6u7v8w9x0y1",
    },
)
print(res.json())

응답

현금영수증 객체가 와요.

{
  "code": "10001",
  "data": {
    "id": "crt_a1b2c3d4e5f6g7h8i9j0k1l2",
    "kind": "ORIGINAL",
    "status": "PENDING",
    "type": "PERSONAL",
    "identifier": "01012345678",
    "selfIssued": false,
    "customerName": "홍길동",
    "amount": 50000,
    "supplyCost": 45455,
    "tax": 4545,
    "method": "MANUAL",
    "invoiceId": "ivc_n0o1p2q3r4s5t6u7v8w9x0y1",
    "invoiceNumber": 1043,
    "ntsConfirmNum": "TB0000123",
    "failure": null,
    "issuedBy": { "type": "API_KEY", "accountId": null, "apiKeyId": "apk_k3l4m5n6o7p8q9r0s1t2u3v4", "name": "쇼핑몰 서버" },
    "...": "..."
  }
}

오류

HTTP code 발생 조건
401 290006 API 키가 올바르지 않아요.
403 290007 읽기 전용 API 키예요.
404 20014 invoiceId의 주문이 없어요.
409 240005 사업자 정보를 등록하지 않았어요.
409 240012 이 주문에 이미 발급했거나 발급 중인 현금영수증이 있어요. data.cashReceiptId에 그 ID가 와요.
422 30007 JSON 본문을 읽을 수 없거나 type, amount가 없어요.
422 220001 invoiceId 형식이 틀렸어요.
422 240002 type이 올바르지 않거나, CORPORATE로 자진발급하려고 했어요.
422 240003 identifier가 type에 맞지 않아요.
422 240004 amount가 1원부터 999,999,999원 사이가 아니에요.
422 240014 customerName이 40자를 넘어요.

이 페이지가 도움이 되었나요?