분쟁

Tokenz의 분쟁 알림으로 분쟁을 처리하는 방법을 알아봅니다.

고객이 은행이나 카드사에 결제 이의를 제기하면 Tokenz가 분쟁을 생성하고 웹훅으로 알립니다. 분쟁 수명 주기를 이해하고 신속하게 대응하면 유리한 결과를 얻을 가능성을 높일 수 있습니다.

개요

분쟁 시스템은 다음 기능을 제공합니다.

• 실시간 알림: 분쟁이 시작되거나 종료되면 웹훅 이벤트를 수신합니다.
• 분쟁 상세 정보: 이의 제기된 금액, 사유, 증빙 제출 기한을 확인합니다.
• 결과 추적: 분쟁 해결 시점과 최종 결과를 확인합니다.

분쟁 수명 주기

분쟁은 다음 절차를 거칩니다.

1. 분쟁 생성: 고객이나 은행이 결제에 이의를 제기합니다.
2. 증빙 제출 기간: evidenceDueBy까지 아이템 지급 기록 등록 API로 아이템 지급 기록을 제출할 수 있습니다.
3. 분쟁 종료: 은행이나 카드사가 최종 결정을 내리고 결과와 함께 분쟁을 종료합니다.

분쟁 상태 값

분쟁은 다음 상태를 가집니다.

• created: 분쟁이 시작되어 해결을 기다리고 있습니다.
• underReview: 증빙이 제출되어 은행이나 카드사가 검토 중입니다. 이 상태에서 제출한 아이템 지급 기록은 은행이나 카드사에 전달되지 않습니다.
• lost: 고객에게 유리한 결정이 내려져 금액이 고객에게 반환되었습니다.
• won: 판매자에게 유리한 결정이 내려져 금액이 차감되지 않았습니다.

분쟁 결과 값

분쟁이 종료되면 outcome 필드가 최종 결과를 나타냅니다.

• lost: 은행이 고객에게 유리한 결정을 내렸습니다.
• won: 은행이 판매자에게 유리한 결정을 내렸습니다.

분쟁 웹훅

분쟁 이벤트 알림을 받도록 웹훅을 설정하세요. Tokenz는 분쟁 생성 및 종료 시 웹훅 이벤트를 전송합니다.

dispute.created

주문에 대한 새 분쟁이 시작되면 발생합니다.

{
  "id": "d4584e9a-2734-4e32-8d3d-3db675ed329a",
  "object": "dispute.created",
  "createdAt": "2026-02-13T14:01:50.158Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "created",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:01:50.158Z"
      }
    }
  }
}

dispute.closed

분쟁이 해결되면 발생합니다. outcome 필드로 승소 또는 패소 여부를 확인하세요.

{
  "id": "aa8ac3b5-6021-4d32-8fde-da600bcf3374",
  "object": "dispute.closed",
  "createdAt": "2026-02-13T14:03:09.220Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "lost",
        "outcome": "lost",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:03:09.220Z",
        "closedAt": "2026-02-13T14:03:09.220Z"
      }
    }
  }
}

분쟁 이벤트 필드

최상위 필드

• id: 웹훅 이벤트의 고유 식별자(UUID)
• object: 이벤트 유형(dispute.created 또는 dispute.closed)
• createdAt: 이벤트 생성 시각(ISO 8601)
• test: 테스트 모드에서 생성된 이벤트인지 여부

분쟁 객체 필드

• id: 분쟁의 고유 식별자
• object: 항상 "dispute"
• orderId: 분쟁이 발생한 주문의 ID
• orderReference: 분쟁이 발생한 주문의 판매자 측 참조 값
• amount: 소비자 통화 기준 분쟁 금액
  • amount: 통화의 최소 단위 값(예: 센트)
  • currency: ISO 4217 통화 코드(예: USD, JPY)
• reason: 분쟁 사유입니다. 예시는 다음과 같습니다.
  • fraudulent: 고객이 승인하지 않은 거래라고 주장합니다.
  • duplicate: 고객이 중복 청구되었다고 주장합니다.
  • product_not_received: 고객이 상품이나 서비스를 받지 못했다고 주장합니다.
  • product_unacceptable: 고객이 상품이나 서비스에 결함이 있거나 설명과 다르다고 주장합니다.
  • unrecognized: 고객이 해당 청구를 인지하지 못합니다.
  • general: 일반적이거나 분류되지 않은 분쟁 사유입니다.
• status: 현재 분쟁 상태(created, underReview, lost, won)
• outcome: 종료된 분쟁의 최종 결과(lost 또는 won). dispute.closed 이벤트에만 포함됩니다.
• createdAt: 분쟁 시작 시각(ISO 8601)
• evidenceDueBy: 증빙 제출 기한(ISO 8601)
• updatedAt: 마지막 업데이트 시각(ISO 8601)
• closedAt: 분쟁 종료 시각(ISO 8601). dispute.closed 이벤트에만 포함됩니다.

분쟁 테스트

실제 자금에 영향 없이 테스트 모드에서 분쟁을 시뮬레이션하여 운영 전 웹훅 처리를 확인할 수 있습니다. 테스트 분쟁은 성공한 테스트 카드 결제에 대해서만 생성할 수 있습니다.

테스트 분쟁 동작 방식

테스트 카드 결제 시 테스트 분쟁 결과(Test Dispute Result)를 지정하면 해당 주문에 모의 분쟁이 자동 생성됩니다. 분쟁은 전체 수명 주기를 거치며 설정된 엔드포인트로 실제 웹훅 이벤트를 전송합니다.

1. 결제 승인: 테스트 분쟁 결과(Test Dispute Result)를 승소(Won) 또는 패소(Lost)로 설정하고 테스트 카드 결제를 성공시키세요.
2. 분쟁 생성: 몇 초 후 주문에 분쟁이 생성되고 dispute.created 웹훅이 전송됩니다. 주문의 분쟁 상태가 disputed로 변경됩니다.
3. 분쟁 종료: 다시 몇 초 후 선택한 결과로 분쟁이 해결되고 dispute.closed 웹훅이 전송됩니다. 주문의 분쟁 상태가 disputeWon 또는 disputeLost로 변경됩니다.

테스트 분쟁 발생시키기

분쟁 결과를 선택한 후 테스트 결제를 성공시키면 위 분쟁 웹훅 예제와 같은 웹훅을 받습니다. dispute.created와 dispute.closed를 모두 올바르게 처리하는지 확인하세요.

테스트 분쟁 결과

테스트 분쟁 웹훅은 설정된 테스트 웹훅 엔드포인트로만 전송됩니다. 이벤트 수신을 위한 테스트 엔드포인트를 설정하세요.