🔔 Webhook 알림

Webhook을 설정하여 알림을 받습니다. HaloPay는 최종 거래 결과를 가맹점에 알립니다. Webhook URL은 **앱 관리 페이지**에서 설정할 수 있습니다.

다음 이벤트가 발생하면 가맹점이 설정한 콜백 인터페이스로 요청이 전송됩니다:

✅ 결제 거래 성공
⏱️ 결제 시간 초과
💡 결제 부족
✅ 출금 성공
❌ 출금 실패

콜백 빈도: 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h. 총: 24h3m50s

콜백 내용은 항상 암호화되어 있습니다. 자세한 내용은 서명을 참조하세요.

Webhook 알림

헤더

이름	값	필수	타입	설명
X-Appid	h3j6k9m2n5p8q1r4t	Y	string	가맹점 고유 자격 증명. 앱 관리 페이지에서 확인할 수 있습니다.
X-Timestamp	1700349280	Y	string	초 단위 타임스탬프(10자리). 요청은 2분간 유효합니다.
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256(body(json 문자열)+timestamp+appKey)
X-EventType	Paid	Y	string	거래 상태 코드

결제 Body

{
  "appid": "ad4cyr8dpfs...",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd...",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

고객이 전액을 지불하지 않더라도 상태 필드를 TO-BE-PAID로 설정한 콜백 알림을 보냅니다. amount_collected 필드에는 지불된 토큰 수가 표시됩니다.

결제 시간 제한을 초과하면 상태 필드를 TIME-OUT으로 설정한 콜백을 보냅니다. amount_collected 필드에도 다시 지불된 토큰 수가 표시됩니다.

출금 Body

{
  "appid": "ad4cyr8dpfs9j2u1",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "currency_id": 75,
  "status": "PAID",  (PAID/FAIL)
  "time": 1773473637,
  "token_amount": "1",
  "trade_no": "202603141533083d1eba01c48c2a873c",
  "txid": "aa23e0aebd2e4c5b82786a5e8b1f414222c7c525a438b95e2cc7d67c81187a5d",
  "type": "TRANSFER"
}

QR 결제 Body

{
  "appid": "1aiqfs0agrd3b9fm", (기본적으로 결제 APPID와 다릅니다.)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407fa0dc7b7744596cad29cbd53c",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WLeb",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvCQ1",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913
}

매개변수

필드	타입	설명
appid	string	가맹점 APPID
trade_no	string	거래 ID
out_trade_no	string	가맹점 주문 ID
amount	string	거래 금액(법정화폐 금액)
token_amount	string	거래 금액(토큰)
chain	string	체인 이름
chain_id	int	체인 ID
type	string	거래 유형("PAYMENT/TRANSFER/QR_PAYMENT")
currency_id	int	전역 고유 통화 ID TokenList
txid	string	온체인 거래 해시
status	string	거래 상태(TO-BE-PAID/PAID/TIME-OUT/FAIL). 주문이 완전히 지불되지 않으면 TO-BE-PAID 콜백이 트리거됩니다.
time	int	최종 온체인 시간(실패 시 타임아웃 기간 반환)
amount_collected	string	사용자가 지불한 토큰 수
contract	string	토큰의 계약 주소, 주요 통화는 ETH/TRX/BNB
from_address	string	결제 지갑 주소
to_address	string	수령 지갑 주소

💡

가맹점은 정보 보안을 위해 서명합니다. 주문 처리에 성공하면 HTTP 응답 본문에 "Success"를 반환하세요. 처리에 실패하면 HaloPay가 재전송을 시도하며 Webhook은 최대 15회까지 재시도합니다(콜백 빈도: 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h, 총 24h3m50s).

📌 예시

Merchant Webhook 서버로의 요청

POST /webhook/callback HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Appid: ad4cyr8dpfs9j2u1
X-Timestamp: 1773471015
X-Sign: e0c6a719ebc366da...
X-EventType: Paid

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",
  "time": 1773471015
}

Merchant Webhook 서버에서의 응답

HTTP/1.1 200 OK
Content-Type: text/plain

Success

Webhook 알림​

📌 예시​

Webhook 알림

📌 예시