주문 상태 추적 설정하기
사용자에게 아이템을 부여하려면 결제가 성공적으로 완료되었는지 확인해야 합니다.
생성된 주문의 상태를 추적하고 유효성을 검사하려면 애플리케이션의 서버 측에서 웹훅 처리를 구성해야 합니다.
엑솔라에는 아이템 구매 및 환불 시 웹훅을 수신하는 두 가지 옵션이 있습니다. 결제 및 거래 데이터와 구매한 아이템에 대한 정보를 별도로 제공받거나 하나의 웹훅으로 결합해 받을 수 있습니다. 기본적으로 모든 신규 프로젝트는 결합된 웹훅을 받습니다.
웹훅을 결합해 수신하려면 계정 관리자에게 문의하거나 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개의 비밀 키를 생성하여 번갈아가며 사용할 수 있습니다.
프로젝트당 하나의 비밀 키만 활성화할 수 있습니다. 변경하려면 다른 키의 행에서 활성으로 설정을 클릭하고 작동을 확인합니다. 새 키로 성공적으로 마이그레이션한 후에는 비활성화된 키를 삭제하는 것이 좋습니다.
웹훅 리스너 추가
웹훅 수신기는 지정된 URL 주소에서 들어오는 웹훅을 수신하고 서명을 생성한 후 엑솔라 웹훅 서버로 응답을 전송할 수 있는 프로그램 코드입니다.
서명 생성
웹훅을 수신할 때는 데이터 전송의 보안을 보장해야 합니다. 이를 위해서는 웹훅 데이터에서 서명을 생성하고 생성된 서명이 HTTP 요청 헤더에 전송된 서명과 일치하는지 확인해야 합니다.
서명 생성 방법:
- 요청 본문과 프로젝트의 비밀 키의 JSON을 연결합니다.
- 첫 번째 단계에서 구한 문자열에 SHA-1 암호화 해시 함수를 적용합니다.
웹훅으로 응답 보내기
웹훅 수신을 확인하려면 서버가 다음을 반환해야 합니다.
- 성공적인 응답의 경우
200,201또는204HTTP 코드 - 지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된
400HTTP 코드
서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx 코드를 반환할 수도 있습니다.
엑솔라 서버가 주문 결제 성공 및 주문 취소 웹훅에 대한 응답을 받지 못하거나 5xx 코드가 포함된 응답을 받은 경우, 다음 일정에 따라 웹훅이 다시 전송됩니다.
- 5분 간격으로 2번
- 15분 간격으로 7번
- 60분 간격으로 10번
웹훅 전송은 처음 시도 후 12시간 이내에 최대 20번까지 시도할 수 있습니다.
결제 및 환불 웹훅의 재시도 로직은 각 웹훅 페이지에 설명되어 있습니다.
엑솔라 서버가 사용자 유효성 검사 웹훅에 대한 응답을 받지 못하거나 400 또는 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으로 이메일을 보내주세요.
오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.
