사용자에게 구매 권한 부여
엑솔라에서 웹훅으로 받은 거래 세부 정보 및 구매한 아이템에 대한 정보를 사용하여 애플리케이션에서 사용자에게 구매 권한을 부여하도록 구현합니다.
엑솔라에는 아이템 구매 및 환불 시 웹훅을 수신하는 두 가지 옵션이 있습니다. 결제 및 거래 데이터와 구매한 아이템에 대한 정보를 별도로 제공받거나 하나의 웹훅으로 결합해 받을 수 있습니다. 기본적으로 모든 신규 프로젝트는 결합된 웹훅을 받습니다.
웹훅을 결합해 수신하려면 계정 관리자에게 문의하거나 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) | 취소된 결제 데이터, 거래 세부 정보 및 구매한 아이템에 대한 정보가 포함되어 있습니다. 구매한 아이템을 제거할 때 이 웹훅 데이터를 사용합니다. |
아래의 구성도는 결합된 웹훅을 사용하여 아이템을 구매하고 반환하는 과정을 보여줍니다.
%%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
participant User as 사용자
participant GameClient as 게임 클라이언트
participant Xsolla as 엑솔라
participant GameServer as 게임 서버
%% Item Purchase
rect rgb(243, 243, 241)
Note over User, GameServer: 아이템 구매
end
User ->> GameClient: 로그인
activate GameClient
GameClient ->> Xsolla: 사용자 인증 요청 전송
activate Xsolla
Xsolla -->> GameClient: JWT/OAuth 2.0 토큰 반환
deactivate Xsolla
GameClient ->> Xsolla: JWT, 프로젝트 ID, 캠페인 매개 변수 전송
activate Xsolla
Xsolla -->> GameClient: 아이템 어레이 반환
deactivate Xsolla
GameClient -->> User: 스토어프런트 표시
deactivate GameClient
User ->> GameClient: 아이템 선택 및 구매 버튼 클릭
activate GameClient
GameClient ->> Xsolla: 주문 요청 생성
deactivate GameClient
activate Xsolla
Xsolla -->> GameClient: 결제 토큰 반환
deactivate Xsolla
activate GameClient
GameClient ->> Xsolla: 수신한 토큰으로 결제 UI URL 열기
deactivate GameClient
activate Xsolla
Xsolla ->> GameServer: 사용자 검증 웹훅 전송
activate GameServer
GameServer -->> Xsolla: 성공 상태 코드 반환
deactivate GameServer
Xsolla -->> User: 결제 UI 표시
deactivate Xsolla
User ->> Xsolla: 결제 방법을 선택하고 결제를 클릭
activate Xsolla
Xsolla ->> GameServer: 주문 웹훅에 대해 결제 성공 전송
activate GameServer
activate GameServer
Note right of GameServer: 사용자에게 구매 권한 부여
deactivate GameServer
GameServer -->> Xsolla: 성공 상태 코드 반환
deactivate GameServer
Xsolla -->> User: 구매 성공 화면 표시
deactivate Xsolla
%% Refund / Chargeback
rect rgb(243, 243, 241)
Note over User, GameServer: 환불/지불 거절
end
User ->> Xsolla: 환불 또는 지불 거절 요청
activate Xsolla
Xsolla ->> GameServer: 주문 취소 웹훅 전송
activate GameServer
activate GameServer
Note right of GameServer: 사용자 인벤토리에서 아이템 삭제
deactivate GameServer
GameServer -->> Xsolla: 성공 상태 코드 반환
deactivate GameServer
Xsolla -->> User: 결제 환불
deactivate Xsolla
아이템 카탈로그 사용자 맞춤 설정이 애플리케이션 측에 구현된 경우, 파트너 측의 카탈로그 사용자 맞춤 설정 처리를 설정하세요.
실제 결제를 받으려면 라이선스 계약을 체결하고 웹훅 처리를 구현하기만 하면 됩니다.
- 웹훅을 별도로 받는 경우 결제, 주문 결제 성공 및 사용자 유효성 검사
- 결합된 웹훅을 받는 경우 주문 결제 성공 및 사용자 유효성 검사
관리자 페이지에서 웹훅 설정하기
웹훅 수신을 활성화하려면:
- 관리자 페이지의 프로젝트에서 프로젝트 설정 > 웹훅 섹션으로 이동합니다.
- 웹훅 서버 입력란에 웹훅을 수신할 서버의 URL을
https://example.com형식으로 지정합니다. 웹훅 테스트 도구에서 찾은 URL을 지정할 수도 있습니다.
- 비밀 키를 생성합니다.
- 비밀 키 섹션에서 키 추가를 클릭합니다.
- 열리는 모달 창에서 일반 목록에서 식별할 수 있는 키 이름을 입력합니다.
- 키 생성을 클릭합니다.
- 비밀 복사를 클릭하고 생성된 키를 저장합니다.
- 완료를 클릭합니다.
- 키가 저장됐는지 확인하고 확인, 닫기를 클릭합니다.
키 권장 사항:
- 생성된 비밀 키를 저장해 간직하세요. 비밀 키는 관리자 페이지에서 생성했을 때 한 번만 볼 수 있습니다.
- 비밀 키를 다른 사람과 공유하지 마세요.
- 비밀 키는 본인의 서버에 저장하고, 바이너리나 프론트 엔드에 저장하지 마세요.
- 웹훅 활성화를 클릭합니다.
비밀 키 순환 사용
프로젝트에서 최대 5개의 비밀 키를 생성하여 번갈아가며 사용할 수 있습니다.
프로젝트당 하나의 비밀 키만 활성화할 수 있습니다. 변경하려면 다른 키의 행에서 활성으로 설정을 클릭하고 작동을 확인합니다. 새 키로 성공적으로 마이그레이션한 후에는 비활성화된 키를 삭제하는 것이 좋습니다.
관리자 페이지에서 웹훅 테스트하기
프로젝트에서 웹훅을 활성화하면 고급 설정 아래에 웹훅 테스트 섹션이 관리자 페이지에 표시됩니다.
다음 웹훅을 테스트할 수 있습니다.
| 웹훅 테스트용 탭 이름 | 웹훅 이름 및 유형 |
|---|---|
| 결제 및 스토어 | 사용자 유효성 검사 > 사용자 유효성 검사(user_validation) |
게임 서비스 > 결합된 웹훅 > 주문 결제 성공(order_paid) | |
게임 서비스 > 결합된 웹훅 > 주문 취소(order_canceled) | |
| 정기 결제 | 사용자 유효성 검사 > 사용자 유효성 검사(user_validation) |
결제 > 결제(payment) | |
| 분쟁 해결 | 부정 결제 방지 > 분쟁 해결(dispute) |
실제 값이 없는 경우 임의의 값을 입력할 수 있습니다.
샌드박스 또는 라이브 모드로 구매할 때 웹훅을 테스트할 수도 있습니다. 환불 테스트는 라이브 모드에서만 사용할 수 있습니다.
웹훅으로 응답 보내기
웹훅 수신을 확인하려면 서버가 다음을 반환해야 합니다.
- 성공적인 응답의 경우
200,201또는204HTTP 코드 - 지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된
400HTTP 코드
서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx 코드를 반환할 수도 있습니다.
다음 단계
- 정기 결제 판매 설정(선택 사항).
- 사용자 인증 설정.
웹훅에서 아이템 정보 구성
items 배열을 통해 주문 결제 성공 및 주문 취소 웹훅에 포함할 아이템 데이터를 구성할 수 있습니다.
추가 매개 변수 포함 활성화
다음을 표시하는 추가 매개 변수의 포함 기능을 활성화하세요.
- 아이템이 무료인지 여부(
is_free) - 아이템이 보너스인지 여부(
is_bonus) - 아이템이 번들의 일부인지 여부(
is_bundle_content)
이러한 매개 변수를 수신하려면 웹훅 설정에 대한 정보 업데이트 API 호출을 사용하여 웹훅을 버전 2로 전환해야 합니다. 버전 1(기본값)에서는 이러한 매개 변수를 사용할 수 없습니다.
추가 매개 변수가 있는 아이템 배열의 예시:
- json
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가 있는 아이템은 제외됩니다.
번들 콘텐츠가 비활성화된 경우의 아이템 배열 예시:
- json
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년 6월 5일오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.
