Xsolla-logo
  • 문서화
  • 계정 생성

개요

웹훅은 시스템에서 발생하는 이벤트에 대한 알림입니다. 특정 이벤트가 발생하면 엑솔라는 이벤트 데이터가 송신되는 HTTP 요청을 애플리케이션에 보냅니다. 이는 일반적으로 JSON 형식의 POST 요청입니다.

이벤트 예시:

  • 아이템 카탈로그와 사용자 상호 작용
  • 주문 결제 또는 취소

설정한 이벤트가 발생하면 엑솔라는 웹훅을 통해 시스템에 해당 이벤트를 알립니다. 그 결과로 다음과 같은 작업을 수행할 수 있습니다.

  • 사용자의 잔액 충전
  • 결제 대금 환불
  • 사용자 계정에서 새 아이템 추가 또는 제거
  • 정기 결제 서비스 제공 시작
  • 부정 결제가 의심되는 경우 사용자 차단

결제 처리 웹훅 워크플로의 예시:

결제 처리 웹훅

엑솔라 상품 및 솔루션으로 작업할 때의 웹훅 설정:

상품/솔루션 필수/선택 웹훅 사용처
결제 필수
  • 사용자 유효성 검사.
  • 결제 성공 또는 결제 환불 시 거래 세부 정보에 대한 정보 수신.
  • 구매한 아이템을 사용자에게 추가하고 주문 취소 시 아이템을 제거.
인게임 스토어 필수
  • 사용자 유효성 검사.
  • 결제 성공 또는 결제 환불 시 거래 세부 정보에 대한 정보 수신.
  • 구매한 아이템을 사용자에게 추가하고 주문 취소 시 아이템을 제거.
Buy Button 선택 사항 게임 키 판매의 경우 사용자 유효성 검사 및 아이템 추가가 필요하지 않습니다. 결제나 주문 취소 등 이벤트 관련 정보를 수신하기 위해 웹훅을 연결할 수 있습니다.
웹훅을 연결하는 경우 들어오는 모든 필수 웹훅을 처리해야 합니다.
정기 결제 선택 사항 정기 결제 생성, 업데이트 또는 취소에 대한 정보를 받습니다. 또는 API를 통해 정보를 요청할 수 있습니다.
웹샵 선택 사항 사용자 인증에 사용. 사용자 ID를 통한 인증을 사용하는 경우. 또는 엑솔라 로그인을 통한 사용자 인증을 사용할 수 있습니다.
디지털 배포 솔루션 선택 사항
  • 사용자 유효성 검사.
  • 엑솔라 측의 거래 ID와 시스템의 거래 ID를 연결.
  • 주문에서 추가 거래 매개 변수를 전송.
  • 구매한 아이템을 사용자에게 추가하고 주문 취소 시 아이템을 제거.

자세한 내용은 디지털 배포 솔루션용 웹훅 설정에 대한 지침에서 확인할 수 있습니다.

필수 웹훅 목록

웹훅이 필요한 제품 및 솔루션을 사용하는 경우 관리자 페이지에서 웹훅을 활성화 및 테스트하고 처리를 설정합니다. 특정 이벤트가 발생하면 웹훅이 순차적으로 전송됩니다. 따라서 웹훅 중 하나를 처리하지 않으면 후속 웹훅이 전송되지 않습니다. 필수 웹훅 목록은 아래와 같습니다.

인게임 스토어/페이먼트 솔루션

인게임 스토어를 완벽하게 운영하려면 메인 웹훅의 처리를 구현해야 합니다.

  • 사용자 유효성 검사(user_validation) - 사용자가 게임에 등록되었는지 확인하기 위해 결제 과정의 여러 단계에서 전송됩니다.
  • 결제(payment) - 주문이 결제될 때 전송되며 결제 데이터와 거래 세부 정보가 포함되어 있습니다.
  • 주문 결제 성공(order_paid) - 결제 웹훅이 성공적으로 처리되면 구매 아이템과 거래 ID에 대한 정보가 포함된 웹훅이 전송됩니다. 웹훅의 데이터를 사용하여 사용자에게 아이템을 추가합니다.
  • 환불(refund) - 주문이 취소될 때 전송되며 취소된 결제 데이터와 거래 세부 정보가 포함되어 있습니다.
  • 주문 취소(order_canceled) - 환불 웹훅이 성공적으로 처리된 경우 전송되며 구매한 아이템에 대한 정보와 취소된 거래의 ID가 포함되어 있습니다. 웹훅의 데이터를 사용하여 구매한 아이템을 제거합니다.

애플리케이션 측에 아이템 카탈로그 개인 설정이 구현된 경우 파트너 측에서 카탈로그 개인화 웹훅을 처리하도록 설정합니다.

참고

실제 결제를 받으려면 결제, 주문 결제 성공, 사용자 유효성 검증 웹훅 처리를 구현하고 라이선스 계약에 서명만 하면 됩니다.

정기 결제

정기 결제 플랜을 자동으로 관리하려면 기본 웹훅 처리를 구현해야 합니다.

  • 사용자 유효성 검사(user_validation) - 사용자가 게임에 등록되었는지 확인하기 위해 결제 과정의 여러 단계에서 전송됩니다.
  • 결제(payment) - 주문이 결제될 때 전송되며 결제 데이터와 거래 세부 정보가 포함되어 있습니다.
  • 생성된 정기 결제(create_subscription) - 결제 웹훅이 성공적으로 처리되었거나 사용자가 평가판 사용 기간이 있는 정기 결제 구매했을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보 및 사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여 사용자에게 정기 결제를 추가할 수 있습니다.
  • 업데이트된 정기 결제(update_subscription) - 정기 결제가 갱신되거나 변경될 때, 결제 웹훅이 성공적으로 처리되었을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보와 사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여 사용자의 정기 결제를 연장하거나 정기 결제 매개 변수를 변경할 수 있습니다.
  • 환불(refund) - 주문이 취소될 때 전송되며 취소된 결제 데이터와 거래 세부 정보가 포함되어 있습니다.
  • 취소된 정기 결제(cancel_subscription) - 환불 웹훅이 성공적으로 처리되었거나 다른 사유로 정기 결제가 취소된 경우 전송됩니다. 여기에는 정기 결제 및 사용자 데이터에 대한 정보가 포함되어 있습니다. 웹훅 데이터를 사용하여 구매한 정기 결제를 사용자로부터 제거합니다.

관리자 페이지에서 웹훅 설정하기

웹훅 수신을 활성화하는 방법:

  1. 관리자 페이지에서 프로젝트를 엽니다.
  2. 사이드 메뉴에서 프로젝트 설정을 클릭한 후 웹훅 탭으로 이동합니다.
  3. 웹훅 서버 필드에서 웹훅을 수신할 서버의 URL을 https://example.com 형식으로 지정합니다. 웹훅 테스트용 도구에서 찾은 URL을 지정할 수도 있습니다.

주의

데이터 전송에는 HTTPS 프로토콜이 사용되며 HTTP 프로토콜은 지원되지 않습니다.

  1. 프로젝트 웹훅에 서명하기 위한 비밀 키는 기본적으로 생성됩니다. 새 비밀 키를 생성하려면 새로 고침 아이콘을 클릭합니다.
  2. 웹훅 활성화를 클릭합니다.

참고

웹훅을 테스트하려면 webhook.site와 같은 전용 웹사이트 또는 ngrok과 같은 플랫폼을 선택할 수 있습니다.

참고

웹훅을 동시에 다른 URL로 보낼 수 없습니다. 관리자 페이지에서 할 수 있는 작업은 먼저 테스트용 URL을 지정한 다음 실제 URL로 바꾸는 것입니다.

웹훅 수신을 비활성화하는 방법:

  1. 관리자 페이지에서 프로젝트를 엽니다.
  2. 사이드 메뉴에서 프로젝트 설정을 클릭한 후 웹훅 탭으로 이동합니다.
  3. 웹훅 비활성화를 클릭합니다.

관리자 페이지에서 웹훅 테스트하기

웹훅을 테스트하면 사용자 측과 엑솔라 측 모두에서 프로젝트를 올바르게 설정하는 데 도움이 돕니다.

다음 웹훅의 수신을 테스트할 수 있습니다.

웹훅 이름 웹훅 유형
사용자 유효성 검사 user_validation
결제 payment
주문 취소 order_canceled
주문 결제 성공 order_paid

웹훅을 성공적으로 설정하면 웹훅 설정 섹션 아래에 웹훅 테스트 섹션이 표시됩니다.

웹훅 테스트 
섹션

참고

테스트 섹션에 테스트를 통과하지 못했다는 경고가 표시되면 웹훅 리스너에서 웹훅 응답 설정을 확인합니다. 테스트 오류의 원인은 테스트 결과에 표시됩니다.

예:

전문 사이트 webhook.site를 테스트에 사용합니다.

잘못된 서명에 대한 응답 테스트 섹션에 오류가 표시됩니다.

이는 엑솔라가 잘못된 서명이 포함된 웹훅을 전송하고 핸들러가 INVALID_SIGNATURE 오류 코드

를 지정하는 4xx HTTP 코드로 응답할 것으로 예상하기 때문에 발생합니다.

webhook.site는 잘못된 서명이 있는 웹훅을 포함하여 모든 웹훅에 응답으로 200 HTTP 코드를 전송합니다. 예상한 4xx HTTP 코드를 구할 수 없으므로 테스트 결과에 오류가 표시됩니다.

테스트 오류

스토어

스토어 탭에서 다음 웹훅을 테스트할 수 있습니다.

테스트 방법:

  1. 웹훅 테스트 섹션에서 스토어 탭으로 이동합니다.
  2. 드롭다운 메뉴에서 아이템 유형을 선택합니다. 선택한 유형의 아이템이 관리자 페이지에 설정되어 있지 않으면 다음을 클릭합니다.
    • 연결 - 이 유형의 아이템이 있는 모듈이 연결되어 있지 않은 경우
    • 구성 - 이전에 모듈을 연결했지만 설정을 완료하지 않은 경우
      버튼을 클릭하면 선택한 아이템의 유형에 해당하는 관리자 페이지 섹션으로 리디렉션됩니다. 아이템을 생성한 후 웹훅 테스트 섹션으로 돌아가 다음 단계를 진행합니다.
  3. 엑솔라 주문 ID 필드에 아무 값이나 입력합니다.
  4. 드롭다운 목록에서 아이템의 SKU를 선택하고 수량을 표시합니다. +를 클릭하고 같은 유형의 아이템을 여러 개 선택하고 이를 새 줄에 추가할 수 있습니다.
  5. 주문 시 비용 지불에 사용할 통화를 선택합니다.
  6. 테스트를 클릭합니다.

주문 결제 성공주문 취소 웹훅은 지정된 데이터가 포함된 웹훅을 제공된 URL로 전송합니다. 각 웹훅 유형의 테스트 결과는 웹훅 테스트 버튼 아래에 표시됩니다.

스토어 테스트 
섹션

결제

결제 탭에서 다음 웹훅을 테스트할 수 있습니다.

테스트하는 방법:

  1. 테스트 섹션에서 결제 탭으로 이동합니다.
  2. 필수 필드에 값을 입력합니다.
    1. 사용자 ID - 테스트 시 문자와 숫자의 조합을 사용할 수 있습니다.
    2. 공개 사용자 ID - 이메일이나 닉네임 등 사용자에게 알려진 ID입니다. 이 필드는 페이 스테이션 > 설정 > 추가 설정 섹션의 프로젝트에서 공개 사용자 ID가 활성화된 경우 표시됩니다.
    3. 통화 - 드롭다운 목록에서 통화를 선택합니다.
    4. 엑솔라 인보이스 ID - 엑솔라 측의 거래 ID입니다. 테스트 시 임의의 숫자 값을 사용할 수 있습니다.
    5. 금액 - 결제 금액입니다. 테스트 시 숫자 값을 사용할 수 있습니다.
    6. 인보이스 ID - 게임 측의 거래 ID입니다. 테스트 시 문자와 숫자의 조합을 사용할 수 있습니다. 성공적인 결제를 위한 필수 매개 변수는 아니지만 거래 ID를 엑솔라 측과 연결하기 위해 전달할 수 있습니다.
  3. 웹훅 테스트를 클릭합니다.

지정된 URL로 데이터가 채워진 웹훅을 받게 됩니다. 성공한 시나리오와 오류가 있는 시나리오 모두에 대한 각 웹훅의 테스트 결과가 웹훅 테스트 버튼 아래에 표시됩니다. 프로젝트에 공개 사용자 ID가 활성화된 경우 사용자 검색 확인 결과도 표시됩니다.

각 웹훅에 대해 성공한 시나리오와 오류가 있는 시나리오를 모두 처리하도록 구성해야 합니다.

 결제 테스트 섹션

웹훅 서버 필드에 URL을 저장하면 웹훅에서 자세한 정보를 수신할 권한을 부여할 수 있는 고급 설정 섹션을 볼 수 있습니다. 이렇게 하려면 각 토글을 으로 설정합니다. 각 권한의 줄에서 해당 설정의 영향을 받는 웹훅 목록을 확인할 수 있습니다.

토글 설명
저장된 결제 계정에 대한 정보 표시 저장된 결제 방식에 대한 정보는 payment_account 사용자 정의 개체에서 전달됩니다.
저장된 결제 방식을 사용한 거래에 대한 정보 표시

정보는 웹훅의 다음 사용자 정의 매개 변수에서 전달됩니다.

  • saved_payment_method:
    • 0 - 저장된 결제 방식이 사용되지 않음
    • 1 - 현재 결제를 진행할 때 결제 방식이 저장됨
    • 2 - 이전에 저장한 결제 방식이 사용됨
  • payment_type:
    • 1 - 일회성 결제
    • 2 - 반복 결제
주문 개체를 웹훅에 추가 주문 관련 정보는 결제 웹훅의 order 개체에서 전달됩니다.
민감한 데이터 없이 필수 사용자 매개 변수만 전송

사용자에 대한 다음 정보만 웹훅에서 전달됩니다.

  • ID
  • 국가
사용자 정의 매개 변수 전송 사용자 정의 토큰 매개 변수 관련 정보가 웹훅에서 전달됩니다.
카드 BIN 및 접미사 표시

은행 카드 번호에 대한 다음 정보가 웹훅에서 전달됩니다.

  • card_bin 매개 변수의 처음 6자리
  • card_suffix의 마지막 4자리
카드 브랜드 표시 결제에 사용된 카드의 브랜드. 예: Mastercard 또는 Visa.

고급 설정

정기 결제

정기 결제 탭에서 다음 웹훅을 테스트할 수 있습니다.

참고

관리자 페이지에서는 기본 사용자 유효성 검사 및 결제 웹훅만 테스트할 수 있습니다. 다른 웹훅 유형을 테스트하려면 다음으로 이동합니다.

참고

웹훅을 테스트하려면 관리자 페이지 > 정기 결제 > 정기 결제 플랜 섹션에 하나 이상의 생성된 정기 결제가 있어야 합니다.

테스트하는 방법:

  1. 테스트 섹션에서 정기 결제 탭으로 이동합니다.
  2. 필수 입력 필드에 값을 입력합니다.
    1. 사용자 ID - 테스트 시 문자와 숫자의 조합을 사용할 수 있습니다.
    2. 엑솔라 인보이스 ID - 엑솔라 측의 트랜잭션 ID입니다. 테스트 시 숫자 값을 사용할 수 있습니다.
    3. 공개 사용자 ID - 사용자에게 알려진 ID(예: 이메일 또는 닉네임). 이 필드는 페이 스테이션 > 설정 > 추가 설정 섹션의 프로젝트에서 공개 사용자 ID가 활성화된 경우에 표시됩니다.
    4. 통화 - 드롭다운 목록에서 통화를 선택합니다.
    5. 플랜 ID - 정기 결제 플랜입니다. 드롭다운 목록에서 플랜을 선택합니다.
    6. 정기 결제 상품 - 드롭다운 목록에서 상품을 선택합니다(선택 사항).
    7. 금액 - 결제 금액입니다. 테스트할 때는 아무 숫자나 사용할 수 있습니다.
    8. 인보이스 ID - 게임 측의 거래 ID입니다. 테스트할 때 문자와 숫자를 조합하여 사용할 수 있습니다. 성공적인 결제를 위한 필수 매개 변수는 아니지만 거래 ID를 엑솔라 측과 연결하기 위해 전달할 수 있습니다.
    9. 평가 기간. 평가 기간 없이 정기 결제 구매를 테스트하거나 정기 결제 갱신을 테스트하려면 0 값을 지정합니다.
  3. 웹훅 테스트를 클릭합니다.

지정된 URL로 데이터가 채워진 웹훅을 받게 됩니다. 성공적인 시나리오와 오류가 있는 시나리오 모두에 대한 각 웹훅의 테스트 결과가 웹훅 테스트 버튼 아래에 표시됩니다.

웹훅 리스너

웹훅 리스너는 지정된 URL 주소로 들어오는 웹훅을 수신하고, 서명을 생성하며, 엑솔라 웹훅 서버로 응답을 전송하는 프로그램 코드입니다.

참고

웹훅 처리를 위한 기성 클래스가 포함된 페이 스테이션 PHP SDK 라이브러리를 사용할 수 있습니다.

애플리케이션 측에서 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197 IP 주소에서 웹훅을 수신하도록 구현합니다.

제한 사항:

  • 애플리케이션의 데이터베이스에 동일한 ID로 성공한 거래가 있으면 안 됩니다.
  • 웹훅 리스너가 데이터베이스에 이미 존재하는 ID로 웹훅을 수신한 경우 이 거래의 이전 처리 결과를 반환해야 합니다. 사용자에게 중복 구매 항목을 추가하고 데이터베이스에 중복 레코드를 생성하는 것은 좋지 않습니다.

서명 생성

웹훅을 수신할 때는 데이터 송신의 보안을 보장해야 합니다. 이를 위해 웹훅 데이터에서 서명을 생성하고 HTTP 요청 헤더에 전송된 서명과 일치하는지 확인해야 합니다. 서명 생성 방법:

  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"
      }
    }'

웹훅에 응답 보내기

웹훅 수신을 확인하려면 서버가 다음을 반환해야 합니다.

  • 성공적인 응답의 경우 200, 201 또는 204 HTTP 코드.
  • 지정한 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된 400 HTTP 코드. 서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx HTTP 코드를 반환할 수도 있습니다.

주문 결제 성공주문 취소 웹훅에 대한 응답이 수신되지 않았거나 5xx 코드가 포함된 응답이 수신된 경우 다음 일정에 따라 웹훅이 재전송됩니다.

  • 5분 간격으로 2번 시도
  • 15분 간격으로 7번 시도
  • 60분 간격으로 10번 시도

웹훅 전송은 첫 번째 시도 후 12시간 이내에 최대 20번까지 시도할 수 있습니다. 결제 웹훅 또는 환불 웹훅에 대한 응답이 수신되지 않거나 '5xx' 코드가 포함된 응답이 수신되면 시간 간격을 늘려서 웹훅을 다시 보냅니다. 12시간 이내에 최대 12번까지 시도할 수 있습니다.

알림

엑솔라에서 결제 환불을 시작했고 환불 웹훅에 대해 `5xx` HTTP 코드가 포함된 응답을 받은 경우 결제 환불 처리가 계속됩니다.

사용자 유효성 검사 웹훅에 대한 응답을 받지 못했거나 400 또는 5xx 코드 응답을 받은 경우 사용자 유효성 검사 웹훅은 재전송되지 않습니다. 이 경우 사용자에게 오류가 표시되며 결제주문 결제 성공 웹훅이 전송되지 않습니다.

오류

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 상태가 비갱신으로 설정되면 보냅니다.
결제 계정 추가 payment_account_add 사용자가 결제 계정을 추가하거나 저장할 때 보냅니다.
결제 계정 제거 payment_account_remove 사용자가 저장된 계정에서 결제 계정을 제거할 때 보냅니다.
웹 상점에서 사용자 유효성 검사 - 사용자가 게임에 존재하는지 확인하기 위해 웹 상점에서 전송됩니다.
파트너 측의 카탈로그 개인 설정 partner_side_catalog 사용자가 스토어와 상호작용할 때 전송됩니다.
주문 결제 성공 order_paid 주문이 결제되면 전송됩니다.
주문 취소 order_canceled 주문이 취소되면 전송됩니다.
분쟁 dispute 새로운 분쟁이 열리면 전송됩니다.