invoice.paid

주문이 결제 완료되면 보내는 이벤트예요. paidTrigger로 자동 매칭, 수동 매칭, 수동 승인, API 호출을 구분해요.

주문이 결제 완료로 바뀌면 보내요. data.paidTrigger로 어떤 경로로 결제 완료됐는지 알 수 있어요.

paidTrigger

페이로드

data는 결제 완료된 주문 페이로드예요. status는 PAID예요.

{
  "id": "evt_f1g2h3i4j5k6l7m8n9o0p1q2",
  "type": "invoice.paid",
  "timestamp": "2026-04-28T03:20:12Z",
  "data": {
    "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
    "number": 1043,
    "status": "PAID",
    "customer": {
      "name": "홍길동",
      "email": "hong@example.com",
      "phoneNumber": "01012345678"
    },
    "amount": 50000,
    "paidAmount": 50000,
    "amountDiff": null,
    "bankAccountIds": [],
    "cashReceipt": null,
    "metadata": { "orderId": "ORDER-2026-0001" },
    "source": "API",
    "createdAt": "2026-04-28T03:14:15Z",
    "updatedAt": "2026-04-28T03:20:12Z",
    "expiresAt": "2026-04-29T03:14:15Z",
    "paidAt": "2026-04-28T03:20:12Z",
    "paidTrigger": "AUTOMATIC_MATCHING",
    "matchedTransactionId": "trx_m1n2o3p4q5r6s7t8u9v0w1x2",
    "canceledAt": null,
    "cancelReason": null,
    "expiredAt": null,
    "reopenedAt": null
  }
}

입금 계좌나 입금자명이 필요하면 matchedTransactionId로 입금 단건 조회를 하세요. 입금 없이 결제 완료된 주문은 matchedTransactionId가 null이에요.

금액이 조금 달라도 매칭으로 결제 완료됐다면 paidAmount가 amount와 다르고, 차이가 amountDiff에 와요. 받은 금액이 모자란 주문을 따로 처리해야 한다면 amountDiff를 확인하세요.

처리 예시

const event = JSON.parse(body);

if (event.type === "invoice.paid") {
  const invoice = event.data;
  const orderId = invoice.metadata.orderId;

  // 이미 처리한 주문이면 건너뛰어요.
  if (orderId && !(await db.isOrderPaid(orderId))) {
    await db.markOrderPaid(orderId, {
      invoiceId: invoice.id,
      paidAmount: invoice.paidAmount,
      trigger: invoice.paidTrigger,
    });
  }
}

res.sendStatus(200);

paidTrigger는 자동 매칭 비율이나 수동 처리 건수를 집계할 때 쓰기 좋아요. 주문 처리 로직은 보통 paidTrigger와 관계없이 같아요.

자주 묻는 질문