결제 로그

결제 로그 페이지는 결제 Webhook 이벤트를 검색하고, 처리 결과를 확인하고, 상세 Webhook 로그 기록을 열어볼 수 있는 화면입니다.

이 화면은 결제 제공업체의 이벤트 이력을 확인하는 용도입니다. Webhook 이벤트가 정상적으로 수신되었는지, 처리되었는지, 실패했는지, 고객 및 청구 데이터와 정상적으로 매핑되었는지 확인할 때 사용합니다.

화면 개요

Payment Logs는 결제 제공업체에서 수신한 결제 관련 이벤트를 기록합니다. 결제 캡처 이벤트, 정기 구독 생성, 정기 구독 업데이트, 처리 실패 기록, 기타 Webhook 알림 등이 포함될 수 있습니다.

목록 화면에서는 각 이벤트의 요약 정보를 보여주고, 상세 화면에서는 Raw Webhook 기록, 요청 Headers, Raw Body, Signature, 처리 결과, 정규화된 Billing Event 데이터를 확인할 수 있습니다.

검색 및 필터

Search & Filter 영역에서는 Keyword, Provider, Event Type, Process Status, 날짜 범위로 특정 결제 이벤트를 찾을 수 있습니다.

Payment Log List

Payment Log List는 Webhook 및 이벤트 이력 기록을 보여줍니다. 각 행은 결제 제공업체에서 수신했거나 Billing 시스템에서 처리한 하나의 이벤트를 의미합니다.

자주 보는 Event Type

Process Status

FAILED 로그가 반드시 결제 실패를 의미하는 것은 아닙니다. iBoard가 수신한 Webhook을 매핑, 파싱, 저장, 정규화하는 과정에서 실패했다는 의미일 수 있습니다.

Payment Log Detail

Detail 버튼을 클릭하면 Payment Log Detail 화면으로 이동합니다. 이 화면에서는 원본 Webhook 요청과 정규화된 Billing Event 데이터를 확인할 수 있습니다.

Webhook Log 영역

Webhook Log 영역은 결제 제공업체에서 수신한 원본 이벤트 정보를 보여줍니다.

Signature

Signature 필드는 Provider에서 전달한 Webhook Signature 값을 보여줍니다. 이 값은 요청이 실제 결제 제공업체에서 온 것인지 검증하는 데 사용됩니다.

Signature 검증은 Webhook 보안에서 매우 중요합니다. Signature가 없거나 올바르지 않으면 해당 Webhook은 신뢰하지 않는 것이 좋습니다.

Headers

Headers 필드는 Webhook 요청과 함께 수신된 HTTP Header 정보를 보여줍니다. Host, Content-Type, Signature, Forwarding 정보, Trace ID 등 HTTP 메타데이터가 포함될 수 있습니다.

Headers는 Webhook 전달 문제, Signature 검증 문제, Reverse Proxy 동작, Provider 통신 문제를 확인할 때 유용합니다.

Raw Body

Raw Body 필드는 결제 제공업체에서 수신한 원본 JSON Payload를 보여줍니다. 이 데이터는 Billing Event로 파싱하고 정규화하는 기준 데이터입니다.

{
    "notificationId": "provider-event-id",
    "eventType": "net.authorize.payment.authcapture.created",
    "webhookId": "provider-webhook-id",
    "payload": {
        "responseCode": 1,
        "authCode": "ABC123",
        "authAmount": 4.00,
        "invoiceNumber": "codeattack",
        "entityName": "transaction",
        "id": "120080997728"
    }
}

Normalized Data

Normalized Data 영역은 iBoard가 Provider의 Raw Payload를 내부 Billing Event 구조로 변환한 결과를 보여줍니다.

권장 작업 순서

1. Admin > Billing > Payment Logs 메뉴를 엽니다.
2. Provider를 선택하거나 All 상태로 둡니다.
3. 특정 Webhook 이벤트를 확인하려면 Event Type을 입력합니다.
4. SUCCESS 또는 FAILED 같은 Process Status를 선택합니다.
5. From과 To로 날짜 범위를 설정합니다.
6. Search 버튼을 클릭합니다.
7. 이벤트 목록에서 고객 매핑, 상태, 메시지를 확인합니다.
8. Detail 버튼을 클릭하여 Webhook 로그를 상세 확인합니다.
9. Signature, Headers, Raw Body, Normalized Data를 확인합니다.
10. Back 버튼으로 목록으로 돌아갑니다.

자주 사용하는 작업

문제 해결

주의사항

• Payment Logs는 Webhook 및 이벤트 처리 이력을 확인하는 화면입니다.
• 이 페이지에서는 결제 거래나 정기 구독을 생성하지 않습니다.
• PROCESSED 상태는 iBoard가 이벤트를 처리했다는 의미입니다.
• FAILED 상태는 Webhook은 수신되었지만 내부 처리 과정에서 실패했다는 의미입니다.
• Raw Body에는 Provider의 원본 Payload가 포함되므로 문제 해결 시 신중하게 확인해야 합니다.
• Webhook Signature와 Secret 설정은 보안상 중요한 정보로 관리해야 합니다.
• Provider 이벤트가 자동으로 고객과 연결되지 않는 경우 고객 매핑이 필요할 수 있습니다.

관리 권장 사항

• Webhook 이력이 많을 경우 날짜 필터를 먼저 설정하세요.
• 처리 문제를 조사할 때는 FAILED 상태부터 확인하세요.
• 특정 Provider 이벤트를 확인할 때는 Event Type으로 검색하세요.
• Webhook 전달 또는 보안 문제를 조사할 때는 Signature와 Headers를 확인하세요.
• 파싱 또는 매핑 로직을 변경하기 전에는 Raw Body를 먼저 확인하세요.
• Webhook Raw Payload나 Secret 정보를 권한 없는 사용자에게 노출하지 마세요.

Payment Logs는 결제 제공업체가 무엇을 보냈고 iBoard가 그것을 어떻게 처리했는지 확인하는 기술적 근거입니다. 결제 이벤트, 정기 구독 업데이트, Webhook 전달, 고객 매핑 문제를 조사할 때 이 화면을 사용하세요.