콜백 구현

언제, 어디로 오나요

• 고객 결제가 승인 완료되면 결제 생성 때 넘긴 CONFIRM_URL로 POST(JSON) 합니다.
• 관리자가 카리페이 운영 콘솔에서 결제를 취소하면 같은 CONFIRM_URL로 취소 알림이 한 번 더 올 수 있습니다. 어느 경우든 조회 API로 현재 상태를 확인하면 안전합니다.
• 사전 등록이 없습니다. 요청마다 다른 URL을 써도 됩니다(거래번호를 경로에 넣는 방식 권장).

본문

{
  "RESULT_CODE": "0000",
  "RESULT_MSG": "",
  "TRANS_SEQNO": "svc20260921120000123",
  "MOBILE_NO": "01012345678",
  "APPROVAL_AMOUNT": "128000",
  "TEMP_VALUE": "order-8812",
  "ORDER_TYPE": "BILL",
  "txId": "12_34_svc20260921120000123",
  "cardCompany": "신한카드",
  "installment": "00",
  "approvalNumber": "12345678",
  "approvalDatetime": "20260921120135",
  "payerName": "홍길동"
}

필드 구성은 늘어날 수 있습니다. 모르는 필드는 무시하도록 파서를 만드세요.

전송·재시도 규칙

반대로 네트워크 사정에 따라 같은 콜백이 두 번 도달할 수도 있습니다(재배포 중 응답 유실 등). 두 경우 모두를 견디는 방법이 아래 멱등 처리입니다.

멱등 처리

1. 콜백 본문을 승인 근거로 쓰지 않습니다. TRANS_SEQNO만 꺼내 searchPayment를 호출합니다.
2. 이미 PAID인 주문이면 200을 응답하고 무시합니다.
3. 상태 전이(PENDING → PAID)는 DB 조건부 갱신(WHERE status = 'PENDING')으로 한 번만 성공하게 합니다.
4. 서비스 제공(이용권 개통·배송)은 전이가 성공한 요청에서만 실행합니다.

const p = await pay.confirmCallback(req.body);         // TRANS_SEQNO 추출 + searchPayment
if (!p.paid) return;                                   // 미승인/취소면 아무것도 하지 않음
const updated = await db.run("UPDATE orders SET status='PAID' WHERE trans_seqno=? AND status='PENDING'", p.transSeqno);
if (updated === 1) await grantService(p.transSeqno);   // 딱 1회

먼저 200을 응답하세요

콜백 핸들러 안에서 외부 API·DB 작업을 오래 하면 타임아웃으로 실패 처리될 수 있습니다. 즉시 200을 응답하고 처리는 큐·비동기로 넘기세요. 조회 API 검증은 비동기 작업 안에서 하면 됩니다.

위조 콜백

콜백에 X-Webhook-Signature 헤더가 붙을 수 있지만 카리페이 내부 서비스 검증용이라 파트너는 검증하지 않습니다. 본문을 믿지 않고 서명된 조회 API로 확인하는 것이 보안 모델입니다. 위조 콜백이 와도 조회 결과가 APPROVE_COMPLETE가 아니면 아무 일도 일어나지 않습니다.