생성된 주문의 상태를 추적하고 유효성을 검사하려면 애플리케이션의 서버 측에서 웹훅 처리를 구성해야 합니다.

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

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

• 결합된 웹훅을 수신하는 경우
• 별도로 제공된 웹훅을 수신하는 경우

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

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

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

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

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

웹훅의 전체 목록과 웹훅 작업에 대한 일반적인 정보는 웹훅 문서를 참조해 주세요.

PHP SDK

웹훅 처리용으로 준비된 클래스 사용.

웹훅 전송 설정

엑솔라 측에서 웹훅 구성 방법:

1. 프로젝트를 관리자 페이지에서 엽니다.
2. 사이드 메뉴에서 프로젝트 설정을 클릭하고 웹훅 세션으로 이동합니다.
3. 웹훅 URL 필드에서 엑솔라가 웹훅을 전송하는 URL을 지정합니다.

4. 웹훅 사용을 클릭합니다.

웹훅 리스너 추가

웹훅 수신기는 지정된 URL 주소에서 들어오는 웹훅을 수신하고 서명을 생성한 후 엑솔라 웹훅 서버로 응답을 전송할 수 있는 프로그램 코드입니다.

서명 생성

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

서명 생성 방법:

1. 요청 본문과 프로젝트의 비밀 키의 JSON을 연결합니다.
2. 첫 번째 단계에서 구한 문자열에 SHA-1 암호화 해시 함수를 적용합니다.

웹훅으로 응답 보내기

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

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

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

엑솔라 서버가 주문 결제 성공 및 주문 취소 웹훅에 대한 응답을 받지 못하거나 5xx 코드가 포함된 응답을 받은 경우, 다음 일정에 따라 웹훅이 다시 전송됩니다.

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

웹훅 전송은 처음 시도 후 12시간 이내에 최대 20번까지 시도할 수 있습니다.

엑솔라 서버가 결제 웹훅 또는 환불 웹훅에 대한 응답을 받지 못하거나 5xx 코드가 포함된 응답을 받은 경우, 웹훅도 증가된 시간 간격으로 다시 전송됩니다. 12시간 동안 최대 12번 시도할 수 있습니다.

엑솔라 서버가 사용자 유효성 검사 웹훅에 대한 응답을 받지 못하거나 400 또는 5xx 코드가 포함된 응답을 받은 경우, 사용자 유효성 검사 웹훅이 다시 전송되지 않습니다.

이 경우 사용자에게 오류가 표시되며 결제와 주문 결제 성공 웹훅은 전송되지 않습니다.

웹훅에서 아이템 정보 구성

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

추가 매개 변수 포함 활성화

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

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

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

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

 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      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

번들 콘텐츠 포함 비활성화

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

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

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

 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 ],

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

개요

엑솔라 이벤트 API를 통해 서버에서 웹훅을 사용하지 않고도 애플리케이션 클라이언트로부터 직접 결제 정보를 수신하고 처리할 수 있는 GetUpdates 서비스를 사용할 수 있습니다. 결제 웹훅을 처리하기 위해 자체 서버를 설정하고 유지 관리할 필요성을 없애 통합 속도를 높이고 간소화하려면 이 통합 옵션을 사용하세요.

게임과 엑솔라 간의 상호작용:

설정 방법

API를 통해 엑솔라로부터 이벤트를 수신하는 방법:

1. 프로젝트 관리자 페이지에서 프로젝트 설정 > 웹훅 섹션으로 이동합니다.
2. API 사용을 클릭합니다. 설정을 자동으로 저장합니다.

3. 애플리케이션 클라이언트에서 https://getupdate.xsolla.com/events 요청을 전송하여 결제 정보를 받습니다. 자세한 정보는 API 레퍼런스를 참조하십시오. 이에 대한 응답으로, 결제 웹훅과 동일한 형식으로 결제 데이터가 제공됩니다.
4. 결제가 성공하면 사용자에게 구매 권한을 부여합니다.

API 참조

사용자에 대한 처리되지 않은 이벤트 목록 가져오기

1GET https://getupdate.xsolla.com/events

보안: 무기명 사용자 JWT 토큰

응답 예시:

 1{
 2  "events": [
 3   {
 4     "id": 49, // event_id
 5     "status": 0,
 6     "created_at": "2025-04-03T21:21:27Z",
 7     "data": {
 8       "notification_type": "payment",
 9       "purchase": {
10         "order": {
11           "id": 000000001,
12           "lineitems": [
13             {
14               "quantity": 1,
15               "sku": "skill"
16             }
17           ]
18         }
19       },
20       ...
21     }
22   }
23 ]
24}

이벤트 처리됨으로 표시

1POST https://getupdate.xsolla.com/events/<event_id>/processed

event_id는 사용자에 대한 처리되지 않은 이벤트 목록 가져오기 API 호출에 대한 응답에서 확보한 events.id 매개 변수입니다.

보안: 무기명 사용자 JWT 토큰