청구서 API 연동

import { CariPayBilling } from "@caripay/sdk";

const billing = await CariPayBilling.login({
  email: process.env.CARIPAY_BILLING_EMAIL,
  password: process.env.CARIPAY_BILLING_PASSWORD,
});

const result = await billing.sendInvoice({
  requestId: "order_20260921_0001",           // 주문별 고유. 재시도 때 같은 값을 다시 씀
  amount: 128000,
  recipient: { name: "홍길동", phone: "01012345678" },
  reason: "9월 이용료",                        // 60자 이내
  message: "9월 30일까지 납부해 주세요.",         // 선택, 200자 이내
  channel: "ALIMTALK_THEN_SMS",               // ALIMTALK | SMS | ALIMTALK_THEN_SMS
  webhookSecret: process.env.CARIPAY_WEBHOOK_SECRET,          // 선택: 웹훅 서명 비밀(ASCII 16~128자)
  webhookUrl: "https://api.example.com/caripay/invoice-hook", // 선택: 결제 완료·취소 알림
});
// result = { accepted: true, requestId: "order_20260921_0001" }

await billing.sendInvoice({
  requestId: "order_20260922_0001",
  recipient: { name: "홍길동", phone: "01012345678" },
  reason: "9월 수강료",
  message: "9월 30일까지 납부해 주세요.",
  items: [{ name: "수학 특강", price: 120000 }, { name: "교재", price: 15000 }], // amount = 135,000
});

청구서 발송
홍길동님 안녕하세요.
카리수학에서 납부 안내드립니다.
[청구내역]
▷청구서 발급처: 카리수학학원
▷청구 사유: 9월 수강료
▷청구금액: 135,000원

[청구 항목]
- 수학 특강 120,000원
- 교재 15,000원

9월 30일까지 납부해 주세요.
아래 버튼을 눌러 청구 내역을 확인하고, 바로 납부해 주세요.

{
  "event": "bill.paid",
  "billId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "order_20260921_0001",
  "transSeqNo": "20260921120000AbCdEf",
  "status": "DONE",
  "amount": 128000,
  "reason": "9월 이용료",
  "paidAt": "2026-09-21T12:01:35",
  "canceledAt": null,
  "occurredAt": "2026-09-21T12:01:36"
}

import { verifyWebhookSignature } from "@caripay/sdk";

app.post("/caripay/invoice-hook", express.raw({ type: "application/json" }), async (req, res) => {
  const ok = verifyWebhookSignature({ secret: process.env.CARIPAY_WEBHOOK_SECRET, signature: req.get("X-CariPay-Signature"), body: req.body });
  if (!ok) return res.sendStatus(400);                          // 서명 불일치·5분 초과
  res.sendStatus(200);                                          // 먼저 200
  const { requestId, billId, event } = JSON.parse(req.body);
  const order = await orders.findByRequestId(requestId);
  if (!order || order.status !== "PENDING") return;             // 멱등
  const detail = await billing.getInvoice(billId);              // 조회로 확정
  if (event === "bill.paid" && detail.bill.status === "DONE") await orders.markPaid(order);
});

const list = await billing.listInvoices({ month: "2026-09", page: 1, size: 50 });
const detail = await billing.getInvoice(list.bills[0].uniqueId);
// detail.bill.status: "PENDING" | "DONE" | "CANCELED"
// detail.sendHistories[0]: { sendType, sendResult, sendChannel, sentAt, errorMessage }