# Webhook - 결제 승인 완료

## 1. Webhook Overview1

### Purpose

[context]
사용자가 결제 수단을 통해 결제 승인을 성공적으로 완료하면 EBP 시스템에서 상점으로 결제 승인 정보를 전송하는 Webhook 이벤트입니다.<br>
이 이벤트를 통해 상점은 결제 승인 상태를 실시간으로 확인하고, 매입 요청이나 주문 확정 등 후속 처리를 진행할 수 있습니다.
[/context]

> **참고**: Webhook 수신을 위해 URL 등록이 필요합니다. (문의: [ebp-server@lge.com](mailto:ebp-server@lge.com))

> **자동 매입(Auto Capture) 관련 유의 사항**:
> - 결제 의사 생성(`payment-intents`) API 호출 시 `autoCapture` 필드를 `true`로 설정한 경우, 결제 승인과 동시에 매입 처리가 진행됩니다.
> - 이 경우 PG사 및 결제 수단 특성에 따라 결제 승인(`PAYMENT_AUTHORIZED`) 웹훅은 발송되지 않고 결제 매입(`PAYMENT_CAPTURED`) 웹훅만 발송될 수 있습니다.
> - 승인 및 매입 웹훅이 모두 발송되는 경우에도 시스템 환경에 따라 두 이벤트의 수신 순서가 보장되지 않으므로, 상점 시스템 설계 시 이를 고려해야 합니다.

### Details

[table:key-value]
| 항목 | 값 |
| :--- | :--- |
| **Webhook Name** | 결제 승인 완료 |
| **Event Type** | `PAYMENT_AUTHORIZED` |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]

@@include:webhook-authentication.md@@

## 3. Data Schema

### 3.1. Payload Data Schema

| depth | Field | Details & Description                                                                                               |
| :--- | :--- |:--------------------------------------------------------------------------------------------------------------------|
| -1 | eventType | [type:string] [req:Yes] [desc:이벤트 유형] [eg:PAYMENT_AUTHORIZED]                                                        |
| -1 | eventTime | [type:string] [req:Yes] [desc:이벤트 발생 시각[tooltip:UTC, ISO-8601]] [eg:2025-12-30T07:19:28Z]                           |
| -1 | data | [type:object] [req:Yes] [desc:결제 승인 상세 데이터]                                                                            |
| 0 | orderNo | [type:string] [req:Yes] [desc:EBP 주문 번호] [eg:ORD_7202603277730794]                                                      |
| 0 | paymentStatus | [type:string] [req:Yes] [desc:결제 상태 코드] [eg:AUTHORIZED] |
| 0 | authorizedAmount | [type:number] [req:Yes] [desc:승인 금액] [eg:1250000]                                                  |
| 0 | currencyCode | [type:string] [req:Yes] [desc:통화 코드. ISO 4217] [eg:KRW]                                               |
| 0 | exponent | [type:number] [req:Yes] [desc:통화 소수점 자리수] [eg:0]                                               |
| 0 | resultCode | [type:string] [req:Yes] [desc:EBP 결과 코드 ('0': 성공)] [eg:0]                                                    |
| 0 | resultMessage | [type:string] [req:Optional] [desc:결과 메시지] [eg:SUCCESS]                                                   |
| 0 | authorizedAt | [type:string] [req:Yes] [desc:EBP 결제 승인 일시[tooltip:UTC, ISO-8601]] [eg:2025-12-30T07:19:28Z]                        |
| 0 | pgProvider | [type:string] [req:Yes] [desc:결제 PG 제공자] [eg:WORLDPAY, CNSPAY]                  |

## 3.2. Payload 예시

### HTTP Request
```http
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
x-webhook-signature: 25f0e... (HMAC-SHA256 Hex String)
x-webhook-signature-timestamp: 1735543168 (Unix Epoch Seconds)

{
  "eventType": "PAYMENT_AUTHORIZED",
  "eventTime": "2025-12-30T07:19:28Z",
  "data": {
    "orderNo": "ORD_7202603277730794",
    "paymentStatus": "AUTHORIZED",
    "authorizedAmount": 1250000,
    "currencyCode": "KRW",
    "exponent": 0,
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "authorizedAt": "2025-12-30T07:19:28Z",
    "pgProvider": "WORLDPAY"
  }
}
```