사용자에게 구매 권한 부여

엑솔라에서 웹훅으로 받은 거래 세부 정보 및 구매한 아이템에 대한 정보를 사용하여 애플리케이션에서 사용자에게 구매 권한을 부여하도록 구현합니다.

엑솔라 측에서는 아이템 구매 및 환불 발생 시 웹훅을 수신하는 두 가지 옵션이 있습니다: 결제 및 거래 데이터 정보와 구매한 아이템 정보는 별도로 전송되거나 하나의 웹훅으로 통합될 수 있습니다. 기본적으로 모든 신규 프로젝트는 통합 웹훅을 수신합니다.

결합된 웹훅을 수신하는 새 옵션으로 전환하려면 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내주세요.

웹훅 수신 옵션에 대한 추가 정보

결합된 웹훅으로 정보 수신:

2025년 1월 22일 이후 관리자 페이지에 등록한 경우, 주문 결제 성공(order_paid) 및 주문 취소(order_canceled) 웹훅의 모든 정보를 받게 됩니다. 이 경우, 결제(payment) 및 환불(refund) 웹훅을 처리하지 않아도 됩니다.

별도로 제공된 웹훅으로 정보 수신:

2025년 1월 22일 이후 관리자 페이지에 등록한 경우, 다음과 같은 웹훅을 받게 됩니다.

결제 데이터와 트랜잭션 세부 사항에 대한 정보가 포함된 결제(payment) 및 환불(refund).
구매한 아이템에 대한 정보가 포함된 주문 결제 성공(order_paid) 및 주문 취소(order_canceled).

유입되는 모든 웹훅을 처리해야 합니다.

인게임 스토어 및 결제 관리를 제대로 운영하려면 메인 웹훅 처리를 구현해야 합니다.

웹훅 이름	설명
사용자 유효성 검사 > 사용자 유효성 검사(`user_validation`)	사용자가 게임에 등록되어 있는지 확인하기 위해 결제를 처리하는 여러 단계에서 전송됩니다.
게임 서비스 > 결합된 웹훅 > 주문 결제 성공(`order_paid`)	여기에는 결제 데이터, 트랜잭션 세부 사항 및 구매한 아이템에 대한 정보가 포함되어 있습니다. 웹훅의 데이터를 사용하여 사용자에게 구매한 아이템을 추가합니다.
게임 서비스 > 결합된 웹훅 > 주문 취소(`order_canceled`)	여기에는 취소된 결제 데이터, 트랜잭션 세부 사항 및 구매한 아이템에 대한 정보가 포함되어 있습니다. 웹훅의 데이터를 사용하여 구매한 아이템을 제거합니다.

다음 구조는 결합된 웹훅을 사용하여 아이템을 구매하고 반품하는 절차를 보여줍니다.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

사용자, 엑솔라 또는 결제 서비스 제공자가 환불 및 지불 거절을 시작할 수 있습니다.

아이템 카탈로그 개인 설정을 애플리케이션 측에서 구현한 경우 파트너 측에서 카탈로그 개인 설정 처리를 설정합니다.

실제 지불을 받으려면 라이센스 계약에 서명하고 웹훅을 처리하기만 하면 됩니다.별도의 웹훅을 수신한 경우

결제, 주문의 성공적인 결제 및 사용자 유효성 검사
결합 웹훅을 수신하는 경우 주문 결제 성공 및 사용자 유효성 검사

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

관리자 페이지에서 프로젝트를 열고 프로젝트 설정 > 웹훅 섹션으로 이동합니다.
웹훅 서버 필드에서 https://example.com 형식으로 웹훅을 수신할 서버의 URL을 지정합니다. 웹훅 테스트용 도구에서 확인한 URL을 지정할 수도 있습니다.
프로젝트 웹훅에 서명하는 비밀 키는 기본값으로 생성됩니다. 새 비밀 키를 생성하려면 새로 고침 아이콘을 클릭합니다.
웹훅 사용을 클릭합니다.

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

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

프로젝트에서 웹훅을 활성화하면 고급 설정 아래에 웹훅 테스트 섹션이 관리자 페이지에 표시됩니다.

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

웹훅 테스트용 탭 이름	웹훅 이름 및 유형
결제 및 스토어	사용자 유효성 검사 > 사용자 유효성 검사(`user_validation`)
	게임 서비스 > 결합된 웹훅 > 주문 결제 성공(`order_paid`)
	게임 서비스 > 결합된 웹훅 > 주문 취소(`order_canceled`)
정기 결제	사용자 유효성 검사 > 사용자 유효성 검사(`user_validation`)
	결제 > 결제(`payment`)
분쟁 해결	부정 결제 방지 > 분쟁 해결(`dispute`)

다음은 결합된 웹훅을 사용한 시나리오 테스트 방법입니다.

실제 값이 없는 경우 임의의 값을 입력할 수 있습니다.

샌드박스 또는 라이브 모드로 구매할 때 웹훅을 테스트할 수도 있습니다. 환불 테스트는 라이브 모드에서만 사용할 수 있습니다.

웹훅으로 응답 보내기

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

성공적인 응답의 경우 200, 201 또는 204 HTTP 코드
지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된 400 HTTP 코드

서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx 코드를 반환할 수도 있습니다.

전체 웹훅 목록 및 메커니즘과 상세한 처리 예제는 웹훅 문서에 설명되어 있습니다.

다음 단계

정기 결제 판매 설정(선택 사항).
사용자 인증 설정.

웹훅에서 아이템 정보 구성

items 배열을 통해 주문 결제 성공 및 주문 취소 웹훅에 포함할 아이템 데이터를 구성할 수 있습니다.

추가 매개 변수 포함 활성화

다음을 표시하는 추가 매개 변수의 포함 기능을 활성화하세요.

아이템이 무료인지 여부(is_free)
아이템이 보너스인지 여부(is_bonus)
아이템이 번들의 일부인지 여부(is_bundle_content)

이러한 매개 변수를 수신하려면 웹훅 설정에 대한 정보 업데이트 API 호출을 사용하여 웹훅을 버전 2로 전환해야 합니다. 버전 1(기본값)에서는 이러한 매개 변수를 사용할 수 없습니다.

추가 매개 변수가 있는 아이템 배열의 예시:

Copy

Full screen

Small screen

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

번들 콘텐츠 포함 비활성화

기본적으로 웹훅에는 번들의 모든 아이템이 개별 아이템 목록으로 포함됩니다. 콘텐츠를 나열하지 않고 번들 자체만 포함하도록 웹훅을 구성할 수 있습니다.

이 경우 번들에 포함된 아이템은 items 배열에 포함되지 않습니다. 위에 표시된 배열에서 번들의 일부인 SKU com.xsolla.gold_1가 있는 아이템은 제외됩니다.

번들 콘텐츠가 비활성화된 경우의 아이템 배열 예시:

Copy

Full screen

Small screen

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

번들 콘텐츠 포함 기능을 비활성화하려면 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내주세요.

의견을 보내 주셔서 감사드립니다!

메시지를 검토한 후 사용자 경험 향상에 사용하겠습니다.

유용한 링크

통합 절차

마지막 업데이트: 2026년 1월 8일

오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.

콘텐츠

관리자 페이지에서 웹훅 설정하기
관리자 페이지에서 웹훅 테스트하기
웹훅으로 응답 보내기
웹훅에서 아이템 정보 구성
추가 매개 변수 포함 활성화
번들 콘텐츠 포함 비활성화