invoice.paid

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

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

`trigger`	발생 조건
`AUTOMATIC_MATCHING`	입금이 들어와 페이싱크가 주문에 자동으로 매칭했어요. 매칭 어시스트로 매칭한 경우도 포함해요.
`MANUAL_MATCHING`	대시보드 입금 내역에서 입금을 주문에 직접 매칭했어요.
`MANUAL_APPROVE`	대시보드 주문에서 주문을 결제 완료로 바꿨어요.
`API_CALL`	주문 결제 완료 처리 API를 호출했어요.

페이로드

필드	타입	설명
`type`	string	`"invoice.paid"`
`invoice`	object	결제 완료된 주문의 주문 객체예요. `paid`는 `true`예요.
`trigger`	string	결제 완료 경로예요. 위 표를 참고하세요.

{
  "type": "invoice.paid",
  "invoice": {
    "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
    "issuerId": "acc_x9y8z7w6v5u4t3s2r1q0p9o8",
    "bankAccountIds": [],
    "customer": {
      "name": "홍길동",
      "email": "hong@example.com",
      "phoneNumber": "01012345678"
    },
    "cashReceipt": null,
    "amount": 50000,
    "paid": true,
    "metadata": { "orderId": "ORDER-2026-0001" },
    "issuedAt": "2026-04-28T03:14:15.000+00:00",
    "expiresAt": "2026-04-29T03:14:15.000+00:00",
    "deletedAt": null
  },
  "trigger": "AUTOMATIC_MATCHING"
}

페이로드에는 입금 정보가 없어요. 입금 계좌나 입금자명이 필요하면 입금 내역 목록 조회에서 search에 주문 ID를 넣어 찾으세요.

처리 예시

const event = JSON.parse(body);

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

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

res.sendStatus(200);

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

자주 묻는 질문

금액 일부만 입금돼도 이벤트가 오나요?

기본 설정에서는 오지 않아요. 입금 금액이 주문 금액과 같아야 자동 매칭돼요. 매칭 어시스트에서 금액이 조금 달라도 매칭을 켜면 정한 범위 안의 차이는 매칭하고, 이때도 invoice.paid가 와요. v1 페이로드에는 실제 입금액이 없으니 v2 웹훅의 paidAmount를 쓰세요.

현금영수증은 언제 발급되나요?

cashReceipt가 있는 주문은 결제 완료와 함께 현금영수증 발급을 요청해요. 발급 결과는 웹훅으로 보내지 않으니 현금영수증 목록 조회나 대시보드 현금영수증 메뉴에서 확인하세요.

같은 주문의 이벤트를 두 번 받을 수 있나요?

받을 수 있어요. 내 서버가 응답하지 않으면 페이싱크가 다시 보내고, 대시보드에서 재전송해도 같은 이벤트가 다시 가요. 수동 매칭을 해제했다가 다시 매칭하면 새 invoice.paid가 와요. 주문 ID를 기준으로 중복을 걸러 주세요.