Xsolla-logo

개요

웹훅을 사용하면 엑솔라에서 발생하는 구성된 이벤트에 대해 빠르게 알림을 받을 수 있습니다. 웹훅을 사용하여 애플리케이션의 백엔드 및 추가 기능을 자동화할 수 있습니다.

알림을 받을 수 있는 이벤트의 예:

  • 게임머니 및 아이템 구매를 포함한 결제
  • 정기 결제 및 구독 작업
  • 환불

구성된 이벤트가 발생하면 엑솔라가 웹훅을 통해 시스템에 알립니다. 예를 들어, 웹훅을 수신한 후 다음을 수행할 수 있습니다:

  • 사용자의 잔액에 추가합니다
  • 새 아이템 잠금을 해제합니다
  • 정기결제 서비스를 시작합니다
  • 부정결제 감지 후 게임유저를 차단합니다

결제 처리 웹훅이 작동하는 방식은 다음과 같습니다.

결제 처리 웹훅

서버 측을 설정합니다

웹훅이 제대로 작동하려면 다음 설정을 적용해야 합니다:

  • 다음 IP 주소의 웹훅을 수락해야 합니다: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
  • 애플리케이션 데이터베이스에 동일한 ID의 트랜잭션이 중복 되어서는 안됩니다.

공지

시스템이 데이터베이스에 이미 존재하는 ID로 웹훅을 다시 보내면 이전 요청 처리 결과를 리턴합니다. 게임유저에게 구매 정보를 다시 제공하거나 데이터베이스에 중복된 값을 생성하지 마십시오.

  • 생성된 서명이 HTTP 헤더에서 통과된 서명과 동일해야 합니다.
  • 오류가 발생한 경우, 코드 400을 반환합니다(예: 필수 매개 변수 누락, 결제 실패). 코드 500은 일시적 서버 오류를 나타냅니다.

주의

엑솔라는 기본 HTTP 응답 코드를 사용하여 결제 알림(IPN) 요청의 성공 또는 실패를 표시합니다. 코드 204는 성공적인 처리를 나타냅니다.

인터넷 연결이 항상 100% 신뢰할 수 있는 것은 아니므로, 웹훅이 소실되거나 지연될 수 있습니다. 이 문제를 해결하기 위해 엑솔라는 수신기에서 웹훅을 수신할 때까지 실패한 웹훅을 다시 보냅니다. 웹훅 재전송은 수신기에서 수신을 확인할 때까지 이전 전송 후 12시간 이내에 전송됩니다. 최대 재시도 횟수는 12회입니다.

주의

연결 문제로 인해 웹훅 소실, 지연, 중복 현상이 나타나더라도 보통 수신측의 자체 논리 오류로 인해 이러한 문제가 발생하는 경우가 많습니다.

서명 요청

전자 서명은 데이터 전송에 보안을 제공합니다. 서명을 생성하려면:

  1. 요청의 JSON 콘텐츠와 프로젝트 시크릿 키를 연결합니다.
  2. 결과 문자열에 SHA-1 해싱을 적용합니다.
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

오류

HTTP 코드 400에 대한 오류 코드:

코드 메시지
INVALID_USER 잘못된 게임유저
INVALID_PARAMETER 잘못된 매개변수
INVALID_SIGNATURE 잘못된 서명
INCORRECT_AMOUNT 잘못된 금액
INCORRECT_INVOICE 잘못된 인보이스
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook 목록

주의

알림 유형은 notification_type 매개변수로 전송됩니다.

웹훅 알림 유형 설명
게임유저 유효성 검사 user_validation 게임 시스템 내 유저의 존재를 확인하기 위해 보냅니다.
사용자 검색 user_search 공개 사용자 ID별로 사용자 정보를 가져오기 위해 보냅니다.
결제 payment 유저가 결제 프로세스를 완료했을 때 보냅니다.
환불 refund 알 수 없는 이유로 결제가 취소되었을 때 보냅니다.
부분 환불 partial_refund 어떤 이유로든 결제를 부분적으로 취소해야 할 때 전송됩니다.
AFS 거부 거래 afs_reject AFS 확인 중에 거래가 거부된 경우 보냅니다.
AFS 업데이트된 차단 목록 afs_black_list AFS 차단 목록이 업데이트될 때 보냅니다.
정기 결제 생성 create_subscription 유저가 정기 결제를 만들면 보냅니다.
업데이트된 정기 결제 update_subscription 정기 결제가 갱신되거나 변경되었을 때 보냅니다.
취소된 정기 결제 cancel_subscription 정기 결제가 취소되었을 때 보냅니다.
비갱신 정기 결제 non_renewal_subscription 상태가 비갱신으로 설정되면 보냅니다.
게임 키 가져오기 get_pincode 엑솔라 API가 게임 키를 얻어야 하는 경우 보냅니다.
게임유저 잔액: 수동 업데이트 user_balance_operation 게임유저 잔액을 직접 변경할 필요가 있을 경우 보냅니다. 작업 유형 — internal.
게임유저 잔액: 결제 user_balance_operation 게임유저가 결제를 진행한 경우 보냅니다. 작업 유형 — payment.
게임유저 잔액: 환불 user_balance_operation 사용자가 결제를 취소할 때 전송됩니다. 작업 유형 — cancellation.
게임유저 잔액: 쿠폰 사용 user_balance_operation 게임유저가 게임에서 쿠폰을 사용하여 아이템이나 게임머니를 구매할 경우 보냅니다. 작업 유형 — coupon.
게임유저 잔액: 구매 user_balance_operation 게임유저가 게임 내에서 구매할 때 보냅니다. 작업 유형 — inGamePurchase.
친구 가져오기 friends_list 게임유저가 친구 목록 요청을 전송할 때 보냅니다.
키 활성화 redeem_key 사용자가 키를 활성화하면 보냅니다.
업그레이드 환불 upgrade_refund 업그레이드가 취소되었을 때 보냅니다.
결제 계정 추가 payment_account_add 사용자가 결제 계정을 추가하거나 저장할 때 보냅니다.
결제 계정 제거 payment_account_remove 사용자가 저장된 계정에서 결제 계정을 제거할 때 보냅니다.