시작하기

개요

엑솔라 API 포함 사항:

엑솔라 API는 REST를 기반으로 구성되어 있습니다. 예측 가능한 리소스 중심의 URL과 함께 API 오류를 HTTP 응답 코드로 표시하도록 구성된 API입니다. 오류를 포함한 API의 모든 응답에서 JSON이 반환됩니다.

HTTP 인증 및 HTTP 동사(verb) 등 상용 HTTP 클라이언트가 이해할 수 있는 기본 HTTP 기능을 사용하며, 교차 원본(cross-origin) 리소스 공유를 지원하여 개발자가 클라이언트측 웹 애플리케이션에서 API 와 보안된 상호작용을 할 수 있도록 했습니다.

엑솔라 API는 다음 Endpoint 경로를 사용합니다.

  • https://api.xsolla.com — 페이 스테이션 API, 스토어 API, 게시자 계정 API
  • https://login.xsolla.com/api — 로그인 API
대부분의 Endpoint 경로에는 merchant_id 매개변수가 포함되어 있습니다. 이는 애플리케이션이 사용자를 대신하여 작업 중임을 나타냅니다.

릴리스 정보

2.0 버전 변경사항:
  • 거래를 내보내기 위한 새 URL: https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/registry.{format}
  • 변경된 응답 형식:
    • 이제 취소된 거래는 다음 필드에 음수 값으로 표시됨:
      • 결제 시스템 고정 수수료
      • Xsolla 수익 배분(고정)
      • 판매세
      • 가상 통화 구매 금액
      • 간단한 체크아웃 구매 금액
      • 아이템 구매 금액
      • 본국 송금 비용
      • 고정 할인 총 금액
      • 사용자 잔액 공제 금액
      • 결제 시스템에서 지급한 금액
      • 잔액으로 구매한 금액
      • 잔액으로 지급한 지불금액
      • PIN 코드 구매 금액
    • 새 필드 추가됨:
      • 결제 시스템 유형 - 결제 유형
      • VAT - 사용자에게 VAT 표시
      • VAT, % - 해당 국가의 VAT 비율
      • 환불 사유 설명 - 환불 사유에 설명 입력
      • 다이렉트 계좌 - 다이렉트 계좌 여부 표시
    • 삭제된 필드:
      • 결제 시스템 외부 수수료율(%)
      • 결제 시스템 외부 수수료 금액
      • 결제 시스템 외부 수수료 통화
      • “공제된 VAT, %”는 “공제된 VAT”가 0인 경우 0으로 설정됩니다.
    • 필드 이름 변경:
      • VAT -> 공제된 VAT
      • VAT (%) -> 공제된 VAT, %
    • 다음 필드는 값이 0인 경우 채워지지 않습니다.
      • 가상 통화 금액
      • 가상 통화 구매 금액
      • 간단한 체크아웃 구매 금액
      • PIN 코드 구매 금액
    • “가상 통화 구매 통화”는 “가상 통화 구매 금액”이 0인 경우 채워지지 않습니다.
    • “간단한 체크아웃 구매 통화”는 “간단한 체크아웃 구매 금액”이 0인 경우 채워지지 않습니다.
    • “PIN 코드 구매 통화”는 “PIN 코드 구매 금액”이 0인 경우 채워지지 않습니다. “PIN 코드 구매 카트 콘텐츠”가 비어 있습니다.

요청및응답

엑솔라 API Endpoint 요청은 다음 HTTP 헤더에 포함되어야 합니다: Authorization. POST와 PUT 요청은 추가적으로 다음 헤더를 포함해야 합니다. Content-Type: application/json.

기본적으로 모든 Endpoint 응답은 응답 본문에 있는 JSON 으로 데이터를 제공하며 Content-Type: application/json 헤더를 포함합니다.

Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Content-Type: application/json

API 변경사항

엑솔라는 API로 기능을 변경할 수 있습니다.

  • 엑솔라는 새로운 API 자원을 추가할 수 있습니다.
  • 엑솔라는 선택적 요청 매개변수를 추가할 수 있습니다.
  • 엑솔라는 기존 API 응답에 대한 새로운 속성을 추가할 수 있습니다.
  • 엑솔라는 나열된 값들의 묶음들로 이루어진 기존 매개변수에 새 값들을 추가할 수 있습니다.
  • 엑솔라는 JSON에 새 webhook 타입들과 매개변수들을 추가할 수 있습니다.
  • 엑솔라는 선택적 HTTP 요청 헤더를 추가할 수 있습니다.
  • 엑솔라는 유효한 매개변수에 유효하지 않은 매개변수 값이 포함된 요청을 거부할 수 있습니다.
  • 지나치게 관대한 파싱으로 인해 승인된 부적절한 형식의 요청들은 파싱로직이 올바르다면 거부될 수도 있습니다.
  • 엑솔라는 언제든지 문서화되지 않은 기능을 추가, 변경 또는 제거할 수 있습니다.
  • 당신의 고객은 이러한 변경사항과 관계없이 계속 운영할 수 있어야만 합니다. 예를 들어, 클라이언트가 알아채지 못한 새로운 JSON 매개변수로 인해 제대로 동작하는 능력이 방해받지는 않습니다.

    버전 관리

    모든 엑솔라 API 방식은 버전 관리를 지원합니다. 현재 버전과 호환되지 않는 변경 사항이 있을 때마다 새 버전을 발행합니다. 이러한 버전은 "v1"/"v2" 등으로 식별하며 URL에 "/merchant"와 같은 식별자가 붙습니다.

    API를 처음으로 사용하는 경우 최신 버전을 사용하도록 합니다. 버전을 생략하는 경우, 기본값으로 첫 번째 버전을 사용합니다.

    Info: 동일한 버전을 사용하는 경우에만 API 무결성이 보장됩니다.

    인증

    Notice: API key는 많은 권한을 가지고 있으므로 안전하게 보관하십시오.

    엑솔라는 HTTP 기본 인증을 을 사용합니다. 기본 인증 사용자 이름에 판매자 ID를 입력하고, 암호에 API key(엑솔라 판매자 계정 의 설정 페이지에 있음) 를 입력합니다.

    모든 API 요청은 HTTPS를 통해 이뤄져야 합니다. 일반 HTTP를 통한 호출은 불가합니다. 모든 요청에 대한 인증이 필요합니다.

    Note: API에 연결하기 위해서는 TLS 1.2 버전 이상을 사용하셔야 함에 유의하십시오.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    예시:
    <?php
    
    use Xsolla\SDK\API\XsollaClient;
    
    $xsollaClient = XsollaClient::factory(array(
        'merchant_id' => MERCHANT_ID,
        'api_key' => API_KEY
    ));
    
    GET /merchant/v2/merchants/{merchant_id}/events/messages HTTP/1.1
    User-Agent: xsolla-api-client/1.0
    Host: api.xsolla.com
    Accept: application/json
    Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
    Content-Type: application/json
    $ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
    -X GET \
    -u merchant_id:merchant_api_key

    Endpoint 형식

    Endpoint 형식이란 처리할 데이터 형식과 해당 데이터에서 수행하는 작업을 나타냅니다. 가장 일반적인 작업은 다음과 같습니다:

    동작 HTTP 방식 설명
    Create POST 해당 형식의 엔터티를 생성하고 유지합니다.
    List GET 입력한 쿼리 파라미터와 일치하는 모든 엔터티에 대한 요약 정보가 리턴됩니다. 특정 엔터티에 대한 전체 정보를 얻으려면 먼저 List endpoint를 통해 엔터티 ID를 가져온 다음 해당 Retrieve endpoint에 ID를 입력합니다.
    Retrieve GET 입력한 식별자와 일치하는 단일 엔터티에 대한 전체 정보를 제공합니다.
    Replace PUT 입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
    Update PATCH 입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
    Delete DELETE 입력한 식별자와 일치하는 기존 엔터티를 삭제합니다.

    날짜 형식

    모든 날짜는 ISO 8601 형식의 문자열로 표현합니다. UTC(예: 2013-01-15T00:00:00Z) 또는 UTC에 시차를 가감한(UTC보다 8시간 늦을 경우의 예: 2013-01-15T00:00:00-08:00) 날짜 문자열을 입력하여 시간대를 표시할 수 있습니다. 시차를 가감한 날짜를 입력할 때는 정확한 서머 타임을 고려하도록 하십시오.

    페이징

    List endpoint 리스트는 리턴한 결과에 페이지를 매길 수도 있습니다. 이 말은 전체 결과를 단일 응답으로 리턴하지않고, 다음 결과와 연결된 응답 헤더와 함께 일부 결과만 리턴 할수있다는 뜻입니다. 이를 위해 offset 및 limit 파라미터 가 사용됩니다.

    오류 처리

    지원 HTTP 오류 목록:

    • 200, 201, 204 — 오류 없음
    • 400 Bad Request — 보통 필수 매개 변수가 누락되었음을 나타냅니다. 자세한내용은 응답 본문을 참조합니다.
    • 401 Unauthorized — 제공된 유효한 API 키가 없습니다.
    • 402 Request Failed — 유효한 매개 변수이지만 요청이 실패했습니다.
    • 403 Forbidden — 권한이 없습니다. 자세한내용은 응답 본문을 참조합니다.
    • 404 Not Found — 요청한 항목이 존재하지 않습니다.
    • 409, 422 — 잘못된 요청 매개 변수입니다.
    • 412 Precondition Failed — 프로젝트가 아직 활성화되지 않았습니다(토큰 가져오기 방식에서 사용).
    • 415 Unsupported Media Type — HTTP 헤더에 "Content-Type: application/json"이 없습니다.
    • 500, 502, 503, 504 Server Errors — 문제가 발생했습니다.

    엑솔라는 기본 HTTP 응답 코드를 사용하여 API 요청의 성공 또는 실패를 표시합니다. 일반적으로 2xx 코드는 성공을 뜻하고, 4xx 코드는 입력한 정보로 인한 오류(예: 필수 파라미터 누락, 인증 실패 등)를 나타내며, 5xx 코드는 엑솔라 서버와 관련된 오류를 나타냅니다.

    하지만 모든 오류를 HTTP응답 코드에 명확히 대응시킬 수 있는 것은 아닙니다. 올바른 요청인 경우에도 성공적으로 완료되지 않으면 422 오류가 반환됩니다.

    모든 API 오류 응답은 json 개체에 다음 필드를 제공합니다.

    {< T "api_table_name" >}} 유형 설명
    http_status_code integer HTTP 코드
    message string 판독 가능한 메시지로서 오류를 설명합니다. 이 메시지는 항상 영문입니다. 특정 오류에 대한 설명은 나중에 변경될 수도 있습니다.
    extended_message string 오류에 대한 확장된 설명입니다.
    request_id string 문제 해결에 도움이 될 수 있는 고유한 ID입니다.
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    토큰

    보다 안전한 결제를 위해 엑솔라 API는 결제 페이지에서 직접 HTTP GET 요청을 통해 데이터를 수신하는 대신 결제 파라미터 목록과 토큰을 사용합니다. 결제 페이지를 호출하기 전에 새 토큰을 가져와야 합니다. 토큰의 유효기간은 24시간.

    토큰 가져오기

    HTTP 요청

    POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

    엑솔라는 어떠한 게임유저 파라미터로도 토큰을 생성할 수 있게 제공합니다. 개발자가 이 파라미터를 전송하면 결제 후 파라미터가 수신됩니다. 토큰에는 모든 게임유저 파라미터가 포함되어 있습니다.

    파라미터 유형 설명
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    object 게임유저 ID 데이터와 관련된 값입니다. 필수.
    user.id.value
    string 사용자 ID.
    user.name
    object 게임유저 닉네임 데이터와 관련된 값입니다.
    user.name.value
    string 게임유저 닉네임입니다.
    user.email
    object 게임유저 이메일 데이터와 관련된 값입니다.
    user.email.value
    string 사용자 이메일. RFC 822 프로토콜에 따라 유효해야 합니다.
    user.phone
    object 사용자 전화번호(오브젝트).
    user.phone.value
    string 전화번호.
    user.country
    object 게임유저 국가 데이터와 관련된 값입니다.
    user.country.value
    string ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
    user.country.allow_modify
    boolean 결제 UI에서 게임유저가 국가를 변경할 수 있는지 여부를 나타냅니다. 기본값은 'false'입니다.
    user.attributes
    object 게임유저 특성 데이터와 관련된 객체로서 아이템 목록을 필터링하는데 사용됩니다. 키값 쌍을 가진 올바른 JSON 해시여야 합니다.
    user.steam_id
    object 게임유저 Steam ID 데이터와 관련된 값입니다.
    user.steam_id.value
    string Steam ID입니다.
    user.tracking_id
    object 사용자 추적 ID에 대한 데이터가 포함된 값입니다.
    user.tracking_id.value
    string 고유한 추적 ID(마케팅 캠페인에 사용됨)입니다.
    user.public_id.value
    string 사용자를 고유하게 식별할 수 있고 사용자 ID(이메일, 애칭 등)와 달리 사용자에 대해 알려진 매개 변수입니다. 이 매개 변수는 게임 스토어 외부(예: 캐시 키오스크의 게임 버튼)에서 구매할 수 있을 때 사용됩니다.
    user.utm
    object 트래픽 성향을 나타내는 데이터를 포함한 오브젝트.
    user.utm.utm_source
    string 트래픽 소스.
    user.utm.utm_medium
    string 트래픽 채널(맥락 이해 광고, 언론 광고, 이메일 목록 메시지).
    user.utm.utm_campaign
    string 캠페인 제목. 이 항목은 음차한 캠페인 제목이나 영어로 번역한 캠페인 제목을 포함해야 합니다.
    user.utm.utm_term
    string 캠페인 키워드. 이 항목을 지정할 경우 광고 캠페인 목표 설정에 사용된 키워드 데이터에 기반하여 통계가 만들어집니다. Google Analytics에서는 utm_term 라벨 콘텐츠가 검색어를 포함한 일반 보고서의 일부가 됩니다.
    user.utm.utm_content
    string 캠페인 구성 요소.
    boolean 게임유저가 법인인지 여부를 나타냅니다.
    object 법인 세부 정보가 있는 오브젝트. user.is_legal가 ‘true’인 경우 오브젝트와 이에 해당하는 모든 매개변수는 필수입니다.
    string 법인 전체 이름.
    string 법인 전체 주소.
    string 개별 납세자 식별자.
    string 기업이 속한 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 대문자 국가 코드를 사용합니다.
    settings
    object 사용자 지정 프로젝트 설정와 관련된 객체입니다.
    settings.external_id
    string 트랜잭션 외부 ID.
    settings.project_id
    integer 엑솔라 시스템 내의 게임 식별자입니다. 판매자 계정 에서 확인할 수 있습니다. 필수.
    settings.language
    string 인터페이스 언어입니다. ISO 639-1 표준에 따른 2자리 언어 코드(소문자)입니다.
    settings.return_url
    string 사용자는 결제 후 이 페이지로 리디렉트됩니다. 파라미터 "user_id", "foreinginvoice", "invoice_id"(와)과 "status"(은)는 자동으로 링크에 추가됩니다.
    settings.currency
    string 선호하는 결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    settings.mode
    string 결제 프로세스를 테스트하기 위한 "sandbox" 값을 설정합니다. 참고로 결제 UI의 URL은 https://sandbox-secure.xsolla.com 이 됩니다.
    settings.payment_method
    integer 결제 수단의 ID입니다.
    settings.payment_widget
    string 결제 위젯. '페이바이캐쉬(paybycash)' 혹은 '기프트카드(giftcard)'일 수 있습니다. 한도가 설정되면, 사용자는 각각 페이바이캐쉬(Pay by Cash) 혹은 기프트 카드(Gift Cards) 위젯으로 다시 보내집니다.
    settings.ui
    object 인터페이스 설정 데이터와 관련된 값입니다.
    settings.ui.theme
    string 결제 UI의 모양 테마입니다. 'default' (기본값) 또는 'default_dark'가 가능합니다.
    settings.ui.size
    string 결제 UI의 크기입니다. 이 매개 변수는 결제 UI의 필요한 크기에 따라 값이 다음과 같을 수 있습니다.
  • small: 결제 UI의 가능한 최소 크기입니다. 창 크기가 엄격히 제한되는 경우 이 값을 사용합니다. (크기: 620 x 630
  • medium: 결제 UI의 권장 크기입니다. 이 값을 사용하여 라이트박스에 결제 UI를 표시합니다. (크기: 740 x 760)
  • large: 새 창 또는 탭에 결제 UI 표시를 위한 최적의 크기입니다. (크기: 820 x 840)
  • settings.ui.version
    string 장치 유형입니다. 'desktop' (기본값) 또는 'mobile'이 가능합니다.
    settings.ui.desktop
    object PC 버전의 인터페이스 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.header
    object 헤더 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.header.is_visible
    boolean 결제 UI에 헤더가 표시되는지 여부를 나타냅니다.
    boolean 'true' 일 경우, 로고가 헤더에 표시됩니다(먼저 관리자에게 로고 파일을 제공할 것).
    settings.ui.desktop.header.visible_name
    boolean 프로젝트 이름이 헤더에 표시되는지 여부를 나타냅니다.
    settings.ui.desktop.header.visible_purchase
    boolean 구매 설명(purchase.description.value)이 헤더에 표시되는지 여부를 나타냅니다. 기본값은 ‘true’입니다.
    settings.ui.desktop.header.type
    string 헤더를 표시하는 설정 방식입니다. 'compact'(프로젝트 이름 및 사용자 ID 표지 안 함) 또는 'normal' (기본값)을 설정할 수 있습니다.
    settings.ui.desktop.header.close_button
    boolean 페이 스테이션 데스크탑에서 닫기 버튼을 표시할지 여부. 이 버튼을 누르면 페이 스테이션이 종료되고"settings.return_url" 매개변수에 지정된 URL로 사용자를 리디렉션합니다(기본값: 'false').
    settings.ui.desktop.subscription_list
    object 정기 결제 목록 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.subscription_list.layout
    string 정기 결제 목록 패턴입니다. 'list' (기본값) 또는 'grid'가 가능합니다.
    settings.ui.desktop.subscription_list.description
    string 정기결제에 관한 어떠한 텍스트도 이곳에서 전달할 수 있습니다. 정기 결제 요금제 목록 위에 텍스트가 표시됩니다.
    settings.ui.desktop.subscription_list.display_local_price
    boolean 'true'인 경우 및 사용자의 현지 통화가 정기결제 플랜의 통화와 다른 경우, 사용자는 현지 통화의 가격 및 기본 통화의 가격과 같이 두 가지 가격을 볼 수 있습니다.
    settings.ui.desktop.virtual_item_list
    object 게임 아이템 목록 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.virtual_item_list.layout
    string 정기 결제 목록 패턴입니다. 'list' (기본값) 또는 'grid'가 가능합니다.
    settings.ui.desktop.virtual_item_list.button_with_price
    boolean 'true'인 경우, 가격이 버튼에 표시됩니다. 'false'인 경우, 가격이 버튼 왼쪽에 표시됩니다. 기본적으로 'false'입니다.
    settings.ui.desktop.virtual_item_list.view
    string 가상 아이템 그룹을 수직/수평 메뉴로 표시합니다. 'horizontal_navigation' 또는 'vertical'(기본)이 가능합니다.
    settings.ui.desktop.virtual_currency_list
    object 게임머니 목록 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.virtual_currency_list.description
    string 게임머니 목록에 관한 어떠한 텍스트도 이곳에서 전달할 수 있습니다. 게임머니 패키지 목록 위에 텍스트가 표시됩니다.
    settings.ui.desktop.virtual_currency_list.button_with_price
    boolean 'true'인 경우, 가격이 버튼에 표시됩니다. 'false'인 경우, 가격이 버튼 왼쪽에 표시됩니다. 기본적으로 'false'입니다.
    settings.ui.header.visible_virtual_currency_balance
    boolean 결제 UI에서 이 요소를 숨길 수 있는지 여부를 나타냅니다. 기본값은 'true'입니다.
    settings.ui.mobile.mode
    string 사용자는 저장된 결제 방법을 통해서만 결제를 할 수 있습니다. 'saved_accounts'일 수 있습니다.
    settings.ui.mobile.header.close_button
    boolean 페이 스테이션 모바일에서 닫기 버튼을 표시할지 여부. 이 버튼을 누르면 페이 스테이션이 종료되고 사용자는 "settings.return_url" 매개변수에서 지정한 URL로 리디렉션됩니다(기본적으로 'false').
    boolean 모바일 버전의 결제 UI에서 바닥글을 표시하거나 숨길지 여부입니다.
    settings.ui.license_url
    string EULA의 링크입니다.
    settings.ui.components
    object 모듈 메뉴 설정 데이터와 관련된 값입니다.
    settings.ui.components.virtual_items
    object 게임 아이템 모듈 설정 데이터와 관련된 값입니다.
    settings.ui.components.virtual_items.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.components.virtual_items.hidden
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다.
    settings.ui.components.virtual_items.selected_group
    string 게임유저가 게임 아이템 탭을 열었을 때 선택되는 그룹입니다.
    settings.ui.components.virtual_items.selected_item
    string 게임유저가 게임 아이템 탭을 열었을 때 선택되는 아이템입니다. 아이템 SKU는 이곳에서 보내야 합니다.
    settings.ui.components.virtual_currency
    object 게임머니 모듈 설정 데이터와 관련된 값입니다.
    settings.ui.components.virtual_currency.custom_amount
    boolean 사용자가 결제 UI에 임의의 가상 통화 수량을 입력할 수 있도록 설정합니다.
    settings.ui.components.virtual_currency.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.components.virtual_currency.hidden
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다.
    settings.ui.components.subscriptions
    object 정기 결제 모듈 설정 데이터와 관련된 값입니다.
    settings.ui.components.subscriptions.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.components.subscriptions.hidden
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다.
    settings.ui.mode
    string 사용자 계정의 결제 인터페이스입니다. 가능한 값은 'user_account'입니다. 헤더에는 제품을 선택하거나 결제를 하기 위한 옵션 없이 사용자 계정의 탐색 메뉴만 포함되어 있고, 사용자 계정은 데스크톱 모드에서만 사용 가능합니다.
    settings.ui.user_account
    object 사용자 계정에 관한 데이터가 담긴 객체.
    settings.ui.user_account.info
    object ‘내 계정’ 페이지입니다.
    settings.ui.user_account.info.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.user_account.info.enable
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다. 기본값은 'false'입니다.
    settings.ui.user_account.history
    object 사용자의 ‘기록’ 페이지입니다.
    settings.ui.user_account.history.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.user_account.history.enable
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다. 기본값은 'false'입니다.
    settings.ui.user_account.payment_accounts
    object ‘내 결제 계정’ 페이지입니다.
    settings.ui.user_account.payment_accounts.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.user_account.payment_accounts.enable
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다. 기본값은 'false'입니다.
    settings.ui.user_account.subscriptions
    object ‘구독 관리’ 페이지입니다.
    settings.ui.user_account.subscriptions.order
    integer 모듈 메뉴에서 게임 아이템의 위치입니다.
    settings.ui.user_account.subscriptions.enable
    boolean 모듈 메뉴에 게임 아이템을 표시하는지 여부를 나타냅니다. 기본값은 'false'입니다.
    settings.shipping_enabled
    boolean 배송 주소 양식을 표시할 지를 설정. 기본값은 'false'입니다.
    purchase
    object 구매 데이터 관련 값입니다.
    purchase.virtual_currency
    object 게임머니 데이터와 관련된 값입니다.
    purchase.virtual_currency.quantity
    float 게임머니 구매량입니다.
    purchase.virtual_currency.currency
    string 모든 계산이 이루어지는 사항에 기반한, 게임머니 통화 패키지의 통화입니다.
    purchase.virtual_items
    object 게임 아이템 구매 데이터와 관련된 값입니다.
    purchase.virtual_items.currency
    string 모든 계산이 이루어지는 사항에 기반한, 구매에서 가상 항목의 통화입니다.
    purchase.virtual_items.items
    array 아이템 구매 데이터와 관련된 배열입니다.
    purchase.virtual_items.items.sku
    string 아이템 ID입니다.
    purchase.virtual_items.items.amount
    integer 아이템 수량입니다.
    purchase.virtual_items.available_groups
    array 아이템 그룹 ID 관련 배열입니다. 지정된 그룹의 아이템만 결제 UI에 표시됩니다.
    purchase.subscription
    object 정기결제 데이터 관련 값입니다.
    purchase.subscription.plan_id
    string 요금제 ID입니다.
    purchase.subscription.operation
    string 사용자의 구독 플랜에 적용되는 작업 유형. 구독 플랜을 변경하려면 ‘change_plan’ 값을 전달합니다. purchase.subscription.plan_id 매개변수에서 새 플랜 ID를 지정해야 합니다.
    purchase.subscription.product_id
    string 제품 ID.
    purchase.subscription.currency
    string 구매 시 플랜의 통화, 이를 바탕으로 모든 계산이 수행됩니다.
    purchase.subscription.available_plans
    array 구독권에 대한 데이터가 있는 배열입니다. 오직 이러한 구독권만 결제 UI에 보여집니다.
    purchase.subscription.trial_days
    integer 평가 기간(일)입니다.
    purchase.pin_codes
    object 게임 키에 데이터가 포함된 값입니다.
    purchase.pin_codes.currency
    string 모든 계산이 이루어지는 사항에 기반한, 구매에서 게임 키의 통화입니다.
    purchase.pin_codes.codes
    array 게임 키에 대한 데이터가 포함된 배열입니다.
    purchase.pin_codes.codes.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.codes.drm
    string DRM 사용이 가능한 게임입니다. 'steam', 'playstation', 'xbox', 'uplay', 'origin' 또는 'drmfree'일 수 있습니다. 판매자 계정에서 필요한 DRM을 구성했는지 확인하십시오. 이 매개 변수가 토큰으로 전달되지 않는 경우 사용자가 결제 인터페이스에서 DRM을 선택할 수 있습니다.
    purchase.pin_codes.upgrade
    object 업그레이드 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.id_user_history
    integer 사용자 및 해당 패키지 데이터가 들어있는 입력 항목의 ID입니다.
    purchase.pin_codes.upgrade.id
    integer 업그레이드 ID.
    purchase.checkout
    object 결제 파라미터 데이터와 관련된 값입니다.
    purchase.checkout.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.checkout.amount
    float 구매 금액입니다.
    purchase.description
    object 구매 설명 데이터와 관련된 값입니다.
    purchase.description.value
    string 구매 설명입니다. UI와 이메일에 표시됩니다.
    purchase.gift
    object 기프트에 대한 데이터를 포함하고 있는 객체입니다.
    purchase.gift.giver_id
    string 제공자 ID.
    purchase.gift.message
    string 제공자로부터 전송된 메시지.
    purchase.gift.hide_giver_from_receiver
    string 수신자에서 제공자 ID를 숨길지 여부(기본값은 'true').
    purchase.gift.friends
    array 친구에 대한 데이터를 포함하고 있는 어레이.
    purchase.gift.friends.id
    string 기프트 수령인 ID.
    purchase.gift.friends.name
    string 기프트 수령인 별칭.
    purchase.gift.friends.email
    string 기프트 수령인 이메일.
    purchase.coupon_code
    object 할인 프로모션 모드 또는 구매에 따른 보너스 정보(오브젝트).
    purchase.coupon_code.value
    string 프로모션 코드값.
    purchase.coupon_code.hidden
    boolean 결제 UI에 입력한 필드 프로모션 코드를 숨깁니다. 기본값은 ‘false’입니다.
    custom_parameters
    object 사용자 지정 파라미터입니다. 키와 값을 쌍으로 가진 올바른 JSON 해시여야 합니다.

    파라미터가 잘못된 형식 또는 유형으로 전송되는 경우 토큰이 제공되지 않게 됩니다. 응답으로, json 본문에 설명된 오류와 함께 422 HTTP 코드를 받게 됩니다. "extended_message"에서 잘못 전송된 매개 변수가 정확히 무엇인지에 대한 정보가 제공됩니다.

    {
        "extended_message": {
            "global_errors": [],
            "property_errors": {
                "settings.project_id": [
                    "string value found, but an integer is required"
                ]
            }
        }
    }

    Copy
    Full screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    요청
    POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
    
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    Content-Type: application/json
    
    Body:
      {
      "purchase": {
        "virtual_currency": {
          "quantity": 100
        },
        "virtual_items": {
          "items": [
            {
              "amount": 1,
              "sku": "SKU01"
            }
          ]
        }
      },
      "settings": {
        "currency": "USD",
        "language": "en",
        "project_id": 16184,
        "ui": {
          "components": {
            "virtual_currency": {
              "custom_amount": true
            }
          },
          "desktop": {
            "virtual_item_list": {
              "button_with_price": true,
              "layout": "list"
            }
          },
          "size": "medium"
        }
      },
      "user": {
        "country": {
          "allow_modify": true,
          "value": "US"
        },
        "email": {
          "value": "john.smith@mail.com"
        },
        "id": {
          "value": "user_2"
        },
        "name": {
          "value": "John Smith"
        }
      }
    }
    curl --request POST \
      --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
      --header 'authorization: Basic <your_authorization_basic_key>' \
      --header 'content-type: application/json' \
      --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
    <?php
    
    $client = new http\Client;
    $request = new http\Client\Request;
    
    $body = new http\Message\Body;
    $body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');
    
    $request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
    $request->setRequestMethod('POST');
    $request->setBody($body);
    
    $request->setHeaders(array(
      'authorization' => 'Basic <your_authorization_basic_key>',
      'content-type' => 'application/json'
    ));
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();
    
    var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
    var request = new RestRequest(Method.POST);
    request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
    request.AddHeader("content-type", "application/json");
    request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
    import http.client
    
    conn = http.client.HTTPSConnection("api.xsolla.com")
    
    payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
    
    headers = {
        'content-type': "application/json",
        'authorization': "Basic <your_authorization_basic_key>"
        }
    
    conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    require 'uri'
    require 'net/http'
    
    url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Post.new(url)
    request["content-type"] = 'application/json'
    request["authorization"] = 'Basic <your_authorization_basic_key>'
    request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
    
    response = http.request(request)
    puts response.read_body
    OkHttpClient client = new OkHttpClient();
    
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
    Request request = new Request.Builder()
      .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
      .post(body)
      .addHeader("content-type", "application/json")
      .addHeader("authorization", "Basic <your_authorization_basic_key>")
      .build();
    
    Response response = client.newCall(request).execute();
    var data = JSON.stringify({
      "user": {
        "id": {
          "value": "user_2"
        },
        "name": {
          "value": "John Smith"
        },
        "email": {
          "value": "john.smith@mail.com"
        },
        "country": {
          "value": "US",
          "allow_modify": true
        }
      },
      "settings": {
        "project_id": 16184,
        "currency": "USD",
        "language": "en",
        "ui": {
          "size": "medium",
          "desktop": {
            "virtual_item_list": {
              "layout": "list",
              "button_with_price": true
            }
          },
          "components": {
            "virtual_currency": {
              "custom_amount": true
            }
          }
        }
      },
      "purchase": {
        "virtual_currency": {
          "quantity": 100
        },
        "virtual_items": {
          "items": [
            {
              "sku": "SKU01",
              "amount": 1
            }
          ]
        }
      }
    });
    
    var xhr = new XMLHttpRequest();
    xhr.withCredentials = true;
    
    xhr.addEventListener("readystatechange", function () {
      if (this.readyState === this.DONE) {
        console.log(this.responseText);
      }
    });
    
    xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
    xhr.setRequestHeader("content-type", "application/json");
    xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
    
    xhr.send(data);
    
    응답
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    {
      "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
    }
    

    추가 매개 변수 목록

    부정 결제 방지 필터를 구성하기 위해 custom_parameters 객체 토큰에 추가 매개변수를 전달할 수 있습니다. 권장하는 매개변수는 아래 표에 제시되어 있습니다. 필요에 따라 목록을 확장할 수 있습니다.

    레시피 보기

    파라미터 유형 설명
    registration_date
    string ISO 8601에 따른 계정 생성일.
    total_hours
    integer 총 인게임 시간.
    total_characters
    integer 인게임 캐릭터 수.
    social_networks_added
    boolean 플레이어가 소셜 미디어 프로필을 연결했는지 여부.
    profile_image_added
    boolean 플레이어가 프로필 이미지를 업로드했는지 여부.
    active_date
    string ISO 8601에 따른 마지막 확인 날짜.
    total_friends
    integer 친구의 수.
    additional_verification
    boolean 플레이어가 계정 확인 절차를 사용하고 있는지 여부.
    win_rate
    integer 승률.
    last_change_password_date
    string ISO 8601에 따른 마지막 암호 변경 날짜.
    chat_activity
    boolean 플레이어의 채팅 기능 사용 여부.
    forum_activity
    boolean 플레이어의 포럼 기능 사용 여부.
    total_bans
    integer 플레이어가 채팅/포럼에서 금지된 횟수.
    profile_completed
    boolean 플레이어가 프로필에 추가 정보를 추가했는지 여부.
    notifications_enabled
    boolean 플레이어가 알림을 활성화했는지 여부.
    user_level
    integer 플레이의 레벨, 명성 또는 순위.
    karma_points
    integer 플레이어의 카르마.
    total_sum
    float 총 결제 금액.
    non_premium_currency
    float 프리미엄이 아닌 통화의 금액.
    total_game_events
    integer 플레이어가 참여했던 인게임 이벤트의 수.
    total_gifts
    integer 플레이어가 전송/수신한 인게임 선물의 수.
    tutorial_completed
    boolean 플레이어가 게임 튜토리얼을 완료했는지 여부.
    completed_tasks
    integer 완료한 임무/목표의 수.
    items_used
    boolean 플레이어가 구매한 인게임 아이템을 사용하고 있는지 여부.
    pvp_activity
    boolean 플레이어가 PvP 전투에 참여하고 있는지 여부.
    total_clans
    integer 플레이어가 가입한 클랜의 수.
    unlocked_achievements
    integer 잠금을 해제한 업적의 수.
    total_inventory_value
    float 인벤토리의 총 가치(인게임 통화).
    character_customized
    boolean 플레이어가 자신의 캐릭터를 맞춤 설정했는지 여부.
    session_time
    string ISO 8601에 따른 평균 세션 시간.

    웹훅

    개요

    엑솔라 트랜잭션에 발생한 이벤트에 대한 알림을 받으려면 Webhook을 사용하십시오. Webhook을 사용하면 상태 및 기타 트랜잭션 관련 정보 제공과 같은 백오피스 및 관리 기능을 자동화할 수 있습니다.

    Webhook은 다음과 같은 이벤트에 대한 알림을 보낼 때 사용하는 서비스입니다:

    • 게임머니 구매,아이템 구매,신용카드 결제 등의 즉시결제
    • 정기결제
    • 트랜잭션과 관련된 승인실패/환불

    많은 경우에 Webhook을 작동시키는 것은 개발자 웹 사이트에서의 게임유저 작업입니다. 하지만 그외 작업도 Webhook을 작동시킬 수 있습니다. 예를 들어, 개발자 사이트의 백오피스 프로세스가 환불을 위해 엑솔라 API를 호출하거나, 결제 시스템이 엑솔라에게 부정 결제를 알릴 수 있습니다.

    Webhook은 개발자가 직접 작성한 프로그램인 수신기(핸들러)를 통해 수신하여 처리합니다. 이 프로그램은 Webhook을 대기했다가, 적절히 응답하여 관리자 프로세스로 전달합니다.

    개발자측 작업의 예:

    • 게임유저의 잔액 충전하기
    • 새 아이템 잠금 해제하기
    • 정기결제 서비스 시작하기
    • 부정결제 감지 후 게임유저 차단하기

    다음 IP 주소의 Webhook을 수락해야 합니다: 185.30.20.0/24, 185.30.21.0/24

    데이터베이스에 동일한 ID의 트랜잭션이 중복 되어서는 안됩니다. 시스템이 데이터베이스에 이미 존재하는 ID로 Webhook을 다시 보내면 이전 요청 처리 결과를 리턴합니다. 게임유저에게 구매 정보를 다시 제공하거나 데이터베이스에 중복된 값을 생성하지 마십시오.

    Webhook 서비스는 알림을 받을 서버에서 모든 Webhook을 수신할 것이라고 가정하지 않습니다. 인터넷은 100% 안정적이지 않기 때문에 Webhook이 소실되거나 지연될 수 있습니다. 이 문제의 해결을 위해 Webhook 서비스에는 서버가 수신을 확인할 때까지 다양한 간격으로 메시지를 재전송하는 기능이 있습니다. Webhook은 원본 메시지를 전송하고 나서 최대 12시간 후까지 재전송할 수 있습니다. 재전송 시도 최대 횟수는 12회입니다.

    Note: 참고: 인터넷에 문제가 있는 경우에도 Webhook 소실, 지연, 중복의 원인은 서버 자체 오류일 가능성이 높습니다.

    서명 요청

    전자 서명은 데이터 전송에 보안을 제공합니다. 서명 생성은 두 가지 단계로 이뤄집니다. 첫 번째 단계는 JSON 콘텐츠와 프로젝트 시크릿 키를 연결하는 것입니다. 두 번째 단계는 첫 번째 단계에서 얻어진 콘텐츠에SHA-1암호화 해시 기능을 사용하는 것으로 구성됩니다.

    생성한 서명이 HTTP 헤더에서 통과된 서명과 동일한지 확인해야 합니다.

    Copy
    Full screen
    http
    • http
    • curl
    요청
    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"}}'

    응답

    엑솔라는 기본 HTTP 응답 코드를 사용하여 결제 알림(IPN) 요청의 성공 또는 실패를 표시합니다. 코드 204는 결제 수신 성공을 나타냅니다. 400 코드를 제공해야 하는 영구적인 오류가 있을 경우, 제공된 정보(예: 필수 파라미터 누락, 결제 실패 등)로 인한 오류를 표시합니다. 코드 500은 일시적 서버 오류를 나타냅니다.

    Webhook 목록

    알림 유형은 notification_type 파라미터로 보냅니다.

    알림 유형 설명
    user_validation 게임 시스템 내 유저의 존재를 확인해 줍니다.
    user_search 공개 사용자 ID별로 사용자 정보를 가져옵니다.
    payment 유저가 결제 프로세스를 완료했을 때 보냅니다.
    refund 알수없는이유로결제가취소되었을때보냅니다.
    afs_reject AFS 확인 중에 거래가 거부된 경우.
    create_subscription 유저가 정기 결제를 만들면 보냅니다.
    update_subscription 정기 결제를 취소되었을 때 보냅니다.
    cancel_subscription 정기 결제를 취소되었을 때 보냅니다.
    get_pincode 게임 키를 얻어야 하는 경우 전송됩니다.
    user_balance_operation 유저 잔고에 변화가 있을 때 보냅니다 (작업 유형을 operation_type 으로 보냄).
    redeem_key 사용자가 키를 활성화하면 보냅니다.
    upgrade_refund 업그레이드가 취소되었을 때 전송합니다.
    inventory_get 게임 인벤토리에서 시장으로 아이템 목록을 가져옵니다.
    inventory_pull 게임 인벤토리에서 시장으로 아이템을 불러옵니다.
    inventory_push 시장에서 게임 인벤토리로 아이템을 내보냅니다.

    게임유저 유효성 검사

    엑솔라 서버가 게임 내 캐릭터 존재를 확인하기 위해 결제 알림 스크립트에 요청을 보냅니다.

    파라미터 유형 설명
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.ip
    string 유저 IP 주소입니다.
    user.phone
    string 유저 전화 번호입니다(국제 형식).
    user.email
    string 사용자 이메일.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.country
    string 사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'user_validation',
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email'=> 'email@example.com',
            'id'=> '1234567',
            'country' => 'US'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "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 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
        "notification_type":"user_validation",
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        }
    }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isUserValidation()) {
           $userArray = $message->getUser();
           $userId = $message->getUserId();
           $messageArray = $message->toArray();
           //TODO if user not found, you should throw InvalidUserException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content
    엑솔라 서버가 공개 사용자 ID별로 사용자에 대한 정보를 가져오기 위해 Webhook URL로 요청을 보냅니다.공개 사용자 ID - 고유하게 사용자를 식별할 수 있고 사용자 ID와 달리 사용자에 대해 알려진 매개 변수(이메일, 애칭 등)입니다. 이 webhook은 게임 스토어 외부에서 구매할 수 있는 경우 사용됩니다(예: 캐시 키오스크의 게임 버튼).

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다. 필수.
    user.public_id
    string 공개 사용자 ID입니다.
    user.id
    string 사용자 ID.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'user_search',
        'user' => array(
            'public_id' => 'public_email@example.com'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type":"user_search",
        "user": {
            "public_id": "public_email@example.com"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
        "notification_type":"user_search",
        "user": {
            "public_id": "public_email@example.com"
        }
    }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    
    $callback = function (Message $message) {
        if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
            $userArray = $message->getUser();
            $userPublicId = $message->getUserPublicId();
            // TODO get a user from your database and fill the user data to model.
            $user = new \Xsolla\SDK\Webhook\User();
            $user->setId('user_id')
                ->setPublicId($userPublicId)
                ->setEmail('user_email') //Optional field
                ->setPhone('user_phone') //Optional field
                ->setName('user_name'); //Optional field
            //TODO if user not found, you should throw InvalidUserException
            return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
        }
    };
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "user": {
            "public_id": "public_email@example.com",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User"
        }
    }
    {
        "user": {
            "public_id": "public_email@example.com",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User"
        }
    }

    결제

    게임유저가 결제 프로세스를 완료할 때마다 트랜잭션 세부 사항을 결제 알림 스크립트에 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    purchase
    object 구매 데이터 관련 값입니다.
    purchase.virtual_currency
    object 구매 게임머니 데이터와 관련된 값입니다.
    purchase.virtual_currency.name
    string 게임머니 이름.
    purchase.virtual_currency.sku
    string 게임머니 패키지 SKU입니다(게임머니 패키지에 대해 설정된 경우).
    purchase.virtual_currency.quantity
    float 가상 항목의 수량입니다.
    purchase.virtual_currency.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.virtual_currency.amount
    float 구매 금액입니다.
    purchase.checkout
    object 결제 파라미터 데이터와 관련된 값입니다.
    purchase.checkout.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.checkout.amount
    float 구매 금액입니다.
    purchase.subscription
    object 정기결제 세부 정보(오브젝트).
    purchase.subscription.plan_id
    string 요금제 ID(API를 통해 생성된 경우, 외부 ID).
    purchase.subscription.subscription_id
    integer 엑솔라 시스템 내의 정기결제 ID입니다.
    purchase.subscription.product_id
    string 상품 ID(액세스 토큰으로 보낸 경우)입니다.
    purchase.subscription.tags
    array 플랜 태그.
    purchase.subscription.date_create
    string 정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    purchase.subscription.date_next_charge
    string 다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    purchase.subscription.currency
    string 정기결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.subscription.amount
    float 구매 금액입니다.
    purchase.virtual_items
    object 게임 아이템 구매 데이터와 관련된 값입니다.
    purchase.virtual_items.items
    array 아이템 구매 데이터와 관련된 배열입니다.
    purchase.virtual_items.items.sku
    string 아이템 ID입니다.
    purchase.virtual_items.items.amount
    integer 아이템 수량입니다.
    purchase.virtual_items.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.virtual_items.amount
    integer 구매 금액입니다.
    purchase.pin_codes
    object 게임 키에 대한 데이터가 포함된 배열입니다.
    purchase.pin_codes.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.drm
    string DRM 사용이 가능한 게임입니다. 'steam', 'playstation', 'xbox', 'uplay', 'origin' 또는 'drmfree'일 수 있습니다. 판매자 계정으로 필요한 DRM을 구성했는지 확인하세요.
    purchase.pin_codes.currency
    string 게임 키의 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.pin_codes.amount
    float PIN 코드의 가격입니다.
    purchase.pin_codes.upgrade
    object 업그레이드 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from
    object 사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.upgrade.digital_content_to
    object 사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.upgrade.currency
    string 구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
    purchase.pin_codes.upgrade.amount
    float 구매 금액입니다.
    purchase.gift
    object 기프트에 대한 데이터를 포함하고 있는 객체입니다.
    purchase.gift.giver_id
    string 제공자 ID.
    purchase.gift.receiver_ID
    string 기프트 수령인 ID.
    purchase.gift.receiver_email
    string 기프트 수령인 이메일.
    purchase.gift.message
    string 제공자로부터 전송된 메시지.
    purchase.gift.hide_giver_from_receiver
    string 수신자에서 제공자 ID를 숨길지 여부(기본으로 'true')
    purchase.total
    object 구매 총 가격 데이터와 관련된 값입니다. 필수.
    purchase.total.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.total.amount
    float 총 구매 금액입니다.
    purchase.promotions
    array 이 트랜잭션에 적용된 프로모션 데이터와 관련된 배열입니다.
    purchase.promotions.technical_name
    string 프로모션의 기술명입니다.
    purchase.promotions.id
    integer 프로모션 ID입니다.
    purchase.coupon
    object 쿠폰 데이터 관련 값입니다(이 트랜잭션에 쿠폰이 사용된 경우).
    purchase.coupon.coupon_code
    string 쿠폰 코드입니다.
    purchase.coupon.campaign_code
    string 쿠폰 캠페인 코드입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.ip
    string 유저 IP 주소입니다.
    user.phone
    string 유저 전화 번호입니다(국제 형식).
    user.email
    string 사용자 이메일.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.country
    string 사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
    user.zip
    string 우편번호.
    transaction
    object 트랜잭션 데이터 관련 값입니다. 필수.
    transaction.id
    integer 트랜잭션 ID입니다.
    transaction.external_id
    string 트랜잭션 외부 ID 입니다.
    transaction.payment_date
    string 결제 날짜입니다.
    transaction.payment_method
    integer 결제 방식 식별자.
    transaction.dry_run
    integer 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다. 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다.
    transaction.agreement
    integer 계약 ID입니다.
    payment_details
    object 결제 내역 관련 값입니다. 필수.
    payment_details.payment
    object 게임유저 결제 데이터 관련 값입니다.
    payment_details.payment.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment.amount
    string 총계.
    payment_details.payment_method_sum
    object 결제 방법에서 청구된 금액에 대한 데이터가 포함된 값입니다.
    payment_details.payment_method_sum.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment_method_sum.amount
    string 총계.
    payment_details.xsolla_balance_sum
    object 엑솔라 잔액에서 청구된 금액에 대한 데이터가 포함된 값입니다.
    payment_details.xsolla_balance_sum.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.xsolla_balance_sum.amount
    string 총계.
    payment_details.payout
    object 지급 내역 관련 값입니다.
    payment_details.payout.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payout.amount
    float 총계.
    payment_details.vat
    object VAT 세율입니다(유럽연합만 해당).
    payment_details.vat.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.vat.amount
    float 총계.
    payment_details.payout_currency_rate
    float 결제 통화를 지급 통화로 환전할 때의 환율입니다.
    payment_details.xsolla_fee
    object 엑솔라 수수료 요율입니다.
    payment_details.xsolla_fee.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.xsolla_fee.amount
    float 총계.
    payment_details.payment_method_fee
    object 결제 방식 수수료율입니다.
    payment_details.payment_method_fee.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment_method_fee.amount
    float 총계.
    payment_details.sales_tax
    object 판매세 규모입니다(미국만).
    payment_details.sales_tax.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.sales_tax.amount
    float 총계.
    payment_details.repatriation_commission
    object 본국 송금 비용에 대한 데이터가 있는 오브젝트. 타사가 엑솔라에 부과.
    payment_details.repatriation_commission.currency
    string 본국 송금 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.repatriation_commission.amount
    float 본국 송금 비용.
    custom_parameters
    object 사용자 지정 파라미터입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'payment',
        'purchase' => array(
            'virtual_currency' => array(
                'name' => 'Coins',
                'quantity' => 100,
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'total' => array(
                'currency' => 'USD',
                'amount' => 9.99
            )
        ),
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email' => 'email@example.com',
            'id' => '1234567',
            'country' => 'US'
        ),
        'transaction' => array(
            'id' => 87654321,
            'payment_date' => '2014-09-23T19:25:25+04:00',
            'payment_method' => 1380,
            'dry_run' => 1
        ),
        'payment_details' => array(
            'payment' => array(
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'vat' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'payout_currency_rate' => 1,
            'payout' => array(
                'currency' => 'USD',
                'amount' => 9.49
            ),
            'xsolla_fee' => array(
                'currency' => 'USD',
                'amount' => 0.19
            ),
            'payment_method_fee' => array(
                'currency' => 'USD',
                'amount' => 0.31
            ),
            'repatriation_commission' => array(
                'currency' => 'USD',
                'amount' => 0.2
            )
        )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1721
    Authorization: Signature 34553d151e656110c656696c919f9a10e05de542
    
    {
        "notification_type":"payment",
        "purchase":{
            "virtual_currency":{
                "name":"Coins",
                "sku":"test_package1",
                "quantity":10,
                "currency":"USD",
                "amount":100
            },
            "subscription":{
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2014-10-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout":{
                "currency":"USD",
                "amount":50
            },
            "virtual_items":{
                "items":[
                    {
                        "sku": "test_item1",
                        "amount":1
                    }
                ],
                "currency":"USD",
                "amount":50
            },
            "total":{
                "currency":"USD",
                "amount":200
            },
            "promotions":[{
                "technical_name":"Demo Promotion",
                "id":"853"
            }],
            "coupon":{
                "coupon_code":"ICvj45S4FUOyy",
                "campaign_code":"1507"
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction":{
            "id":1,
            "external_id":1,
            "payment_date":"2014-09-24T20:38:16+04:00",
            "payment_method":1,
            "dry_run":1,
            "agreement":1
        },
        "payment_details":{
            "payment":{
                "currency":"USD",
                "amount":230
            },
            "vat": {
                "currency": "USD",
                "amount": 0
            },
            "payout_currency_rate": 1,
            "payout":{
                "currency":"USD",
                "amount":200
            },
            "xsolla_fee":{
                "currency":"USD",
                "amount":10
            },
            "payment_method_fee":{
                "currency":"USD",
                "amount":20
            },
            "repatriation_commission":{
                "currency":"USD",
                "amount":"10"
            }
        },
        "custom_parameters":{
            "parameter1":"value1",
            "parameter2":"value2"
        }
    }
    $curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
        "notification_type":"payment",
        "purchase":{
            "virtual_currency":{
                "name":"Coins",
                "sku":"test_package1",
                "quantity":10,
                "currency":"USD",
                "amount":100
            },
            "subscription":{
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2014-10-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout":{
                "currency":"USD",
                "amount":50
            },
            "virtual_items":{
                "items":[
                    {
                        "sku": "test_item1",
                        "amount":1
                    }
                ],
                "currency":"USD",
                "amount":50
            },
            "total":{
                "currency":"USD",
                "amount":200
            },
            "promotions":[{
                "technical_name":"Demo Promotion",
                "id":"853"
            }],
            "coupon":{
                 "coupon_code":"ICvj45S4FUOyy",
                 "campaign_code":"1507"
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction":{
            "id":1,
            "external_id":1,
            "payment_date":"2014-09-24T20:38:16+04:00",
            "payment_method":1,
            "dry_run":1,
            "agreement":1
        },
        "payment_details":{
            "payment":{
                "currency":"USD",
                "amount":230
            },
            "vat": {
                "currency": "USD",
                "amount": 0
            },
            "payout_currency_rate": 1,
            "payout":{
                "currency":"USD",
                "amount":200
            },
            "xsolla_fee":{
                "currency":"USD",
                "amount":10
            },
            "payment_method_fee":{
                "currency":"USD",
                "amount":20
            },
            "repatriation_commission":{
                "currency":"USD",
                "amount":"10"
            }
        },
        "custom_parameters":{
            "parameter1":"value1",
            "parameter2":"value2"
        }
    }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isPayment()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $paymentDetailsArray = $message->getPaymentDetails();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $messageArray = $message->toArray();
            // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    환불

    엑솔라 서버가 취소할 결제 내역을 결제 알림 스크립트에 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    purchase
    object 구매 데이터 관련 값입니다.
    purchase.virtual_currency
    object 구매 게임머니 데이터와 관련된 값입니다.
    purchase.virtual_currency.name
    string 게임머니 이름.
    purchase.virtual_currency.quantity
    float 가상 항목의 수량입니다.
    purchase.virtual_currency.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.virtual_currency.amount
    float 구매 금액입니다.
    purchase.checkout
    object 결제 파라미터 데이터와 관련된 값입니다.
    purchase.checkout.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.checkout.amount
    float 구매 금액입니다.
    purchase.subscription
    object 정기결제 세부 정보(오브젝트).
    purchase.subscription.plan_id
    string 요금제 ID(API를 통해 생성된 경우, 외부 ID).
    purchase.subscription.tags
    array 플랜 태그.
    purchase.subscription.subscription_id
    integer 엑솔라 시스템 내의 정기결제 ID입니다.
    purchase.subscription.date_create
    string 정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    purchase.subscription.currency
    string 정기결제 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.subscription.amount
    float 구매 금액입니다.
    purchase.virtual_items
    object 게임 아이템 구매 데이터와 관련된 값입니다.
    purchase.virtual_items.items
    array 아이템 구매 데이터와 관련된 배열입니다.
    purchase.virtual_items.items.sku
    string 아이템 ID입니다.
    purchase.virtual_items.items.amount
    integer 아이템 수량입니다.
    purchase.virtual_items.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.virtual_items.amount
    integer 구매 금액입니다.
    purchase.pin_codes
    object 게임 키에 데이터가 포함된 값입니다.
    purchase.pin_codes.upgrade
    object 업그레이드 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from
    object 사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.upgrade.digital_content_to
    object 사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.upgrade.currency
    string 구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
    purchase.pin_codes.upgrade.amount
    float 구매 금액입니다.
    purchase.total
    object 구매 총 가격 데이터와 관련된 값입니다.
    purchase.total.currency
    string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    purchase.total.amount
    float 총 구매 금액입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.ip
    string 유저 IP 주소입니다.
    user.phone
    string 유저 전화 번호입니다(국제 형식).
    user.email
    string 사용자 이메일.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.country
    string 사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
    user.zip
    string 우편번호.
    transaction
    object 트랜잭션 데이터 관련 값입니다. 필수.
    transaction.id
    integer 트랜잭션 ID입니다.
    transaction.external_id
    string 트랜잭션 외부 ID 입니다.
    transaction.dry_run
    integer 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다. 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다.
    transaction.agreement
    integer 계약 ID입니다.
    refund_details
    object 환불 세부 정보(오브젝트).
    refund_details.code
    integer 코드 ID.
    refund_details.reason
    string 환불 이유입니다.
    refund_details.author
    string 환불 개시 프로그램.
    payment_details
    object 결제 내역 관련 값입니다. 필수.
    payment_details.payment
    object 게임유저 결제 데이터 관련 값입니다.
    payment_details.payment.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment.amount
    string 총계.
    payment_details.payment_method_sum
    object 결제 방법에서 청구된 금액에 대한 데이터가 포함된 값입니다.
    payment_details.payment_method_sum.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment_method_sum.amount
    string 총계.
    payment_details.xsolla_balance_sum
    object 엑솔라 잔액에서 청구된 금액에 대한 데이터가 포함된 값입니다.
    payment_details.xsolla_balance_sum.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.xsolla_balance_sum.amount
    string 총계.
    payment_details.payout
    object 지급 내역 관련 값입니다.
    payment_details.payout.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payout.amount
    float 총계.
    payment_details.vat
    object VAT 세율입니다(유럽연합만 해당).
    payment_details.vat.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.vat.amount
    float 총계.
    payment_details.payout_currency_rate
    float 결제 통화를 지급 통화로 환전할 때의 환율입니다.
    payment_details.xsolla_fee
    object 엑솔라 수수료 요율입니다.
    payment_details.xsolla_fee.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.xsolla_fee.amount
    float 총계.
    payment_details.payment_method_fee
    object 결제 방식 수수료율입니다.
    payment_details.payment_method_fee.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.payment_method_fee.amount
    float 총계.
    payment_details.sales_tax
    object 판매세 규모입니다(미국만).
    payment_details.sales_tax.currency
    string 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.sales_tax.amount
    float 총계.
    payment_details.repatriation_commission
    object 본국 송금 비용에 대한 데이터가 있는 오브젝트. 타사가 엑솔라에 부과.
    payment_details.repatriation_commission.currency
    string 본국 송금 통화. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
    payment_details.repatriation_commission.amount
    float 본국 송금 비용.
    custom_parameters
    object 사용자 지정 파라미터입니다.

    환불 코드:

    코드 환불 이유 설명
    1. Cancellation by the user request / the game request. 판매자 계정에서 취소가 요청된 경우 사용됩니다.
    2. Chargeback. 이 트랜잭션의 승인거절이 있을 경우 사용됩니다.
    3. Integration Error. 엑솔라와 게임 사이의 연동에 문제가 있을 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    4. Fraud. 부정결제 가능성이 있을 경우 사용됩니다.
    5. Test Payment. 테스트 트랜잭션인 경우 사용되며 이후 취소로 이어집니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    6. Expired Invoice. 후불 결제 방식에 의해 트랜잭션이 이뤄진 경우 사용됩니다.
    7. PS debt cancel. 결제 방식에 의해 트랜잭션이 이뤄졌지만 지급 거절된 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    8. Cancellation by the PS request. 결제시스템이 취소를 요청한 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    9. Cancellation by the user request. 게임유저의 요청에 의한 환불 사유입니다. 어떤 이유로 게임유저가 게임 또는 구매에 만족하지 못한 못하였음을 의미합니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    10. Cancellation by the game request. 게임이 취소를 요청한 경우 사용됩니다. 이 경우 유저를 차단하는 것은 권장되지 않습니다.
    11. Account holder called to report fraud. 계정 소유자가 본인 미사용 결제로 신고한 경우입니다.
    12. Friendly fraud. 우호적인 부정결제에 대한 메시지를 수신했을 때 사용됩니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'refund',
        'purchase' => array(
            'virtual_currency' => array(
                'name' => 'Coins',
                'quantity' => 100,
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'total' => array(
                'currency' => 'USD',
                'amount' => 9.99
            )
        ),
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email' => 'email@example.com',
            'id' => '1234567',
            'country' => 'US'
        ),
        'transaction' => array(
            'id' => 87654321,
            'payment_date' => '2014-09-23T19:25:25+04:00',
            'payment_method' => 1380,
            'dry_run' => 1
        ),
        'refund_details' => array(
                'code' => 1,
                'reason' => 'Fraud'
        ),
        'payment_details' => array(
            'payment' => array(
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'vat' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'payout_currency_rate' => 1,
            'payout' => array(
                'currency' => 'USD',
                'amount' => 9.49
            ),
            'xsolla_fee' => array(
                'currency' => 'USD',
                'amount' => 0.19
            ),
            'payment_method_fee' => array(
                'currency' => 'USD',
                'amount' => 0.31
            ),
            'repatriation_commission' => array(
                'currency' => 'USD',
                'amount' => 0.2
            )
        )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    
    {
        "notification_type":"refund",
        "purchase":{
            "virtual_currency":{
                "name": "Coins",
                "quantity":10,
                "currency":"USD",
                "amount":100
            },
            "subscription":{
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout":{
                "currency":"USD",
                "amount":50
            },
            "virtual_items":{
                "items":[
                    {
                        "sku": "test_item1",
                        "amount":1
                    }
                ],
                "currency":"USD",
                "amount":50
            },
            "total":{
                "currency":"USD",
                "amount":200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction":{
            "id":1,
            "external_id":1,
            "dry_run":1,
            "agreement":1
        },
        "refund_details":{
            "code":1,
            "reason":"Fraud"
        },
        "payment_details":{
            "xsolla_fee":{
                "currency":"USD",
                "amount":"10"
            },
            "payout":{
                "currency":"USD",
                "amount":"200"
            },
            "payment_method_fee":{
                "currency":"USD",
                "amount":"20"
            },
            "payment":{
                "currency":"USD",
                "amount":"230"
            },
            "repatriation_commission":{
                "currency":"USD",
                "amount":"10"
            }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
            "notification_type":"refund",
            "purchase":{
                "virtual_currency":{
                    "name": "Coins",
                    "quantity":10,
                    "currency":"USD",
                    "amount":100
                },
                "subscription":{
                    "plan_id": "b5dac9c8",
                    "subscription_id": "10",
                    "date_create": "2014-09-22T19:25:25+04:00",
                    "currency": "USD",
                    "amount": 9.99
                },
                "checkout":{
                    "currency":"USD",
                    "amount":50
                },
                "virtual_items":{
                    "items":[
                        {
                            "sku": "test_item1",
                            "amount":1
                        }
                    ],
                    "currency":"USD",
                    "amount":50
                },
                "total":{
                    "currency":"USD",
                    "amount":200
                }
            },
            "user": {
                "ip": "127.0.0.1",
                "phone": "18777976552",
                "email": "email@example.com",
                "id": "1234567",
                "name": "Xsolla User",
                "country": "US"
            },
            "transaction":{
                "id":1,
                "external_id":1,
                "dry_run":1,
                "agreement":1
            },
            "refund_details":{
                "code":1,
                "reason":"Fraud"
            },
            "payment_details":{
                "xsolla_fee":{
                    "currency":"USD",
                    "amount":"10"
                },
                "payout":{
                    "currency":"USD",
                    "amount":"200"
                },
                "payment_method_fee":{
                    "currency":"USD",
                    "amount":"20"
                },
                "payment":{
                    "currency":"USD",
                    "amount":"230"
                },
                "repatriation_commission":{
                    "currency":"USD",
                    "amount":"10"
                }
            }
        }
    }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isRefund()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $paymentDetailsArray = $message->getPaymentDetails();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $refundArray = $message->getRefundDetails();
            $messageArray = $message->toArray();
            // TODO if you cannot handle the refund, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    업그레이드 환불

    사용자가 업그레이드와 관련된 결제를 환불하면 엑솔라는 취소된 모든 업그레이듣 및 현재 게임 패키지를 웹훅 URL로 전송합니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형. 필수.
    purchase
    object 구매 데이터가 있는 객체입니다. 필수.
    purchase.pin_codes
    object 구매한 게임 패키지 데이터가 있는 객체입니다.
    purchase.pin_codes.purchase_type
    string 구매 유형. "일반"(패키지 구매) 또는 "업그레이드"(패키지 업그레이드) 가능.
    purchase.pin_codes.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.currency
    string 구매 통화입니다. ISO 4217에 따른 3자리 통화 코드입니다.
    purchase.pin_codes.amount
    float 구매 금액입니다.
    purchase.pin_codes.transaction
    object 거래 데이터가 있는 객체입니다.
    purchase.pin_codes.transaction.id
    integer 트랜잭션 ID입니다.
    purchase.pin_codes.upgrade
    object 업그레이드 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from
    object 사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string 게임 DRM플랫폼.
    purchase.pin_codes.upgrade.digital_content_to
    object 사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string 게임 DRM플랫폼.
    소유권
    object 사용자가 소유한 패키지의 데이터가 있는 객체입니다. 필수.
    ownership.digital_content
    string 판매자 계정으로 설정된 게임의 SKU입니다.
    ownership.DRM
    string 게임 DRM플랫폼.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array (
      'notification_type' => 'upgrade_refund',
      'purchase' =>
      array (
        'pin_codes' =>
        array (
          0 =>
          array (
            'purchase_type' => 'regular',
            'digital_content' => 'silver',
            'DRM' => 'drmfree',
            'currency' => 'USD',
            'amount' => '40',
            'transaction' =>
            array (
              'id' => '361697569',
            ),
          ),
          1 =>
          array (
            'purchase_type' => 'upgrade',
            'upgrade' =>
            array (
              'digital_content_from' =>
              array (
                'digital_content' => 'silver',
                'DRM' => 'drmfree',
              ),
              'digital_content_to' =>
              array (
                'digital_content' => 'gold',
                'DRM' => 'drmfree',
              ),
            ),
            'currency' => 'USD',
            'amount' => '20',
            'transaction' =>
            array (
              'id' => '361697570'
            ),
          ),
          2 =>
          array (
            'purchase_type' => 'upgrade',
            'upgrade' =>
            array (
              'digital_content_from' =>
              array (
                'digital_content' => 'gold',
                'DRM' => 'drmfree',
              ),
              'digital_content_to' =>
              array (
                'digital_content' => 'platinum',
                'DRM' => 'drmfree',
              ),
            ),
            'currency' => 'USD',
            'amount' => '20',
            'transaction' =>
            array (
              'id' => '361697571'
            ),
          ),
        ),
      ),
      'ownership' =>
      array (
        'digital_content' => NULL,
        'DRM' => NULL,
      ),
    )
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Authorization: Signature <signature>
    
    {
      "notification_type": "upgrade_refund",
      "purchase": {
        "pin_codes": [
          {
            "purchase_type": "regular",
            "digital_content": "silver",
            "DRM": "drmfree",
            "currency": "USD",
            "amount": "40",
            "transaction": {
              "id": "361697569"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "silver",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "gold",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697570"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "gold",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "platinum",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697571"
            }
          }
        ]
      },
      "ownership": {
        "digital_content": null,
        "DRM": null
      }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
      "notification_type": "upgrade_refund",
      "purchase": {
        "pin_codes": [
          {
            "purchase_type": "regular",
            "digital_content": "silver",
            "DRM": "drmfree",
            "currency": "USD",
            "amount": "40",
            "transaction": {
              "id": "361697569"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "silver",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "gold",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697570"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "gold",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "platinum",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697571"
            }
          }
        ]
      },
      "ownership": {
        "digital_content": null,
        "DRM": null
      }
    }'
    응답

    AFS 거부 거래

    AFS 확인 중에 거래가 거부된 경우, 엑솔라에서 거래 세부 정보를 URL 웹훅으로 전송합니다. 이 알림을 활성화하려면 계정 관리자에게 문의하세요.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.ip
    string 유저 IP 주소입니다.
    user.phone
    string 유저 전화 번호입니다(국제 형식).
    user.email
    string 사용자 이메일.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.country
    string 사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.
    user.zip
    string 우편번호.
    transaction
    object 트랜잭션 데이터 관련 값입니다. 필수.
    transaction.id
    integer 트랜잭션 ID입니다.
    transaction.external_id
    string 트랜잭션 외부 ID 입니다.
    transaction.dry_run
    integer 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다. 테스트 트랜잭션 (1 - 테스트 / 0 - 실제)입니다.
    transaction.agreement
    integer 계약 ID입니다.
    refund_details
    object 환불 세부 정보(오브젝트).
    refund_details.code
    integer 코드 ID.
    refund_details.reason
    string 환불 이유입니다.
    refund_details.author
    string 환불 개시 프로그램.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'afs_reject',
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email' => 'email@example.com',
            'id' => '1234567',
            'country' => 'US'
        ),
        'transaction' => array(
            'id' => 87654321,
            'payment_date' => '2014-09-23T19:25:25+04:00',
            'payment_method' => 1380,
            'dry_run' => 1
        ),
        'refund_details' => array(
                'code' => 4,
                'reason' => 'Potential fraud'
        )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    
    {
        "notification_type":"afs_reject",
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "semail@example.com,
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction":{
            "id":1,
            "external_id":1,
            "dry_run":1,
            "agreement":1
        },
        "refund_details":{
            "code":4,
            "reason":"Potential fraud"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
      "notification_type":"afs_reject",
      "user": {
          "ip": "127.0.0.1",
          "phone": "18777976552",
          "email": "semail@example.com,
          "id": "1234567",
          "name": "Xsolla User",
          "country": "US"
      },
      "transaction":{
          "id":1,
          "external_id":1,
          "dry_run":1,
          "agreement":1
      },
      "refund_details":{
          "code":4,
          "reason":"Potential fraud"
      }
    }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isRefund()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $refundArray = $message->getRefundDetails();
            $messageArray = $message->toArray();
            // TODO if you cannot handle the refund, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    정기결제 생성

    게임유저가 정기결제를 한 경우, 이에 대한 알림 메시지를 결제알림 스크립트를 통해 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    subscription
    object 정기결제 데이터 관련 값입니다.
    subscription.plan_id
    string 요금제 ID(API를 통해 생성된 경우, 외부 ID).
    subscription.tags
    array 플랜 태그.
    subscription.subscription_id
    integer 엑솔라 시스템 내의 정기결제 ID입니다.
    subscription.product_id
    string 상품 ID(액세스 토큰으로 보낸 경우)입니다.
    subscription.date_create
    string 정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    subscription.date_next_charge
    string 다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    subscription.trial
    object 정기결제 평가 기간 데이터와 관련된 값입니다.
    subscription.trial.value
    integer 무료체험 기간 길이입니다.
    subscription.trial.type
    string 평가 기간 형식(day)입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'create_subscription',
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_create' => '2014-09-22T19:25:25+04:00',
            'date_next_charge' => '2015-01-22T19:25:25+04:00',
            'trial' =>  array(
                    'value' =>  90,
                    'type' =>  'day'
                )
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type":"create_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type":"create_subscription",
            "user":{
                "id":"1234567",
                "name":"Xsolla User"
            },
            "subscription":{
                "plan_id":"b5dac9c8",
                "subscription_id":"10",
                "product_id":"Demo Product",
                "date_create":"2014-09-22T19:25:25+04:00",
                "date_next_charge":"2015-01-22T19:25:25+04:00",
                "trial": {
                        "value": 90,
                        "type": "day"
                    }
            }
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof CreateSubscriptionMessage) {
           $messageArray = $message->toArray();
           // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    업데이트된 정기결제

    정기결제의 일부 매개 변수("plan_id", "date_next_charge")가 변경된 경우 그리고 정기결제 갱신 시마다, 당사는 해당 webhook URL의 "update_subscription" 알림을 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    subscription
    object 정기결제 데이터 관련 값입니다.
    subscription.plan_id
    string 요금제 ID(API를 통해 생성된 경우, 외부 ID).
    subscription.tags
    array 플랜 태그.
    subscription.subscription_id
    integer 엑솔라 시스템 내의 정기결제 ID입니다.
    subscription.product_id
    string 상품 ID(액세스 토큰으로 보낸 경우)입니다.
    subscription.date_next_charge
    string 다음 충전 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'update_subscription',
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_next_charge' => '2015-01-22T19:25:25+04:00'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type":"update_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type":"update_subscription",
            "user":{
                "id":"1234567",
                "name":"Xsolla User"
            },
            "subscription":{
                "plan_id":"b5dac9c8",
                "subscription_id":"10",
                "product_id":"Demo Product",
                "date_next_charge":"2015-01-22T19:25:25+04:00"
            }
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
      if ($message instanceof UpdateSubscriptionMessage) {
         $messageArray = $message->toArray();
         // TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
      }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    취소된 정기결제

    어떤 이유로 정기결제가 취소된 경우,이에 대한 알림 메시지를 결제알림 스크립트를 통해 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다. 필수.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    subscription
    object 정기결제 데이터 관련 값입니다.
    subscription.plan_id
    string 요금제 ID(API를 통해 생성된 경우, 외부 ID).
    subscription.tags
    array 플랜 태그.
    subscription.subscription_id
    integer 엑솔라 시스템 내의 정기결제 ID입니다.
    subscription.product_id
    string 상품 ID(액세스 토큰으로 보낸 경우)입니다.
    subscription.date_create
    string 정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    subscription.date_end
    string 정기결제 종료 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'notification_type' => 'cancel_subscription',
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_create' => '2014-09-22T19:25:25+04:00',
            'date_end' => '2015-01-22T19:25:25+04:00',
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type":"cancel_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type":"cancel_subscription",
            "user":{
                "id":"1234567",
                "name":"Xsolla User"
            },
            "subscription":{
                "plan_id":"b5dac9c8",
                "subscription_id":"10",
                "product_id":"Demo Product",
                "date_create":"2014-09-22T19:25:25+04:00",
                "date_end":"2015-01-22T19:25:25+04:00"
            }
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof CancelSubscriptionMessage) {
           $messageArray = $message->toArray();
           // TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    게임 키 가져오기

    게임유저가 각 구매를 성공적으로 마친 후에 게임 활성화 코드를 얻기 위해 귀사의 서버로 API 호출을 진행합니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    pin_code
    object 게임 키에 대한 데이터가 포함된 값입니다.
    pin_code.digital_content
    string 게임의 SKU입니다.
    pin_code.DRM
    string DRM 사용이 가능한 게임입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array (
           'notification_type' => 'get_pincode',
           'user' =>
               array (
                   'id' => '1234567',
                   'name' => 'Xsolla User',
               ),
           'pin_code' =>
               array (
                   'digital_content' => 'Game SKU',
                   'DRM' => 'Steam',
               ),
       );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type":"get_pincode",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "pin_code":{
            "digital_content":"Game SKU",
            "DRM":"Steam"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type":"get_pincode",
            "user":{
                "id":"1234567",
                "name":"Xsolla User"
            },
            "pin_code":{
                "digital_content":"Game SKU",
                "DRM":"Steam"
            }
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof GetPinCodeMessage) {
            $userArray = $message->getUser();
            $drmSku = $message->getDRM();
            $digitalContentSku = $message->getDigitalContent();
            // TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
            $newPinCode = 'NEW_PIN_CODE';
            // TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
            return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
        }
    };
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    {
        "pin_code": "PIN_CODE"
    }

    키 활성화

    사용자가 키를 활성화하면 엑솔라는 알림 메시지를 웹훅 URL로 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형.
    key
    string 활성화 키.
    sku
    string 고유 키 패키지 ID.
    user_id
    string 사용자 ID.
    activation_date
    datetime ISO 8601에 따라 키 활성화 날짜는 YYYYMMDDHHMMSS형식입니다.
    user_country
    string 사용자 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 대문자 국가 코드를 사용합니다.
    restriction
    object 지역 제한 클러스터 설정이 있는 오브젝트. 클러스터는 제한 유형과 게임을 이용할 수 있는 국가, 서버, 로캘 목록을 포함합니다.
    restriction.sku
    string 고유 클러스터 ID.
    restriction.name
    string 클러스터 이름.
    restriction.types
    array 제한 유형 배열.
    restriction_countries
    array 클러스터의 국개 바열.
    restriction.servers
    array 게임 서버 배열.
    restriction.locales
    array 로캘 배열.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    $request = array(
        'notification_type' => 'redeem_key',
        'key' => ‘wqdqwwddq9099022’,
        'sku' => 123,
        'user_id' => ‘sample_user’,
        'activation_date' => ‘2018-11-20T08:38:51+03:00,
        'user_country' => ‘EN’,
        'restriction' =>
               array(
                    'name' => ‘cls_1’,
                    'types' =>
                            array(
                                ‘activation’
                            ),
                    'countries' =>
                            array(
                                ‘RU’
                            ),
                 ),
    );  
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 165
    Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
    
    {
      "notification_type": "redeem_key",
      "key": "wqdqwwddq9099022",
      "sku": "123",
      "user_id": "sample_user",
      "activation_date": "2018-11-20T08:38:51+03:00",
      "user_country": "EN",
      "restriction": {
          "name": "cls_1",
          "types": [
               "activation"
            ],
            "countries": [
                 "RU"
            ]
      }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
         "notification_type": "redeem_key",
      "key": "wqdqwwddq9099022",
      "sku": "123",
      "user_id": "sample_user",
      "activation_date": "2018-11-20T08:38:51+03:00",
      "user_country": "EN",
      "restriction": {
          "name": "cls_1",
          "types": [
               "activation"
            ],
            "countries": [
                 "RU"
             ]
        }
    }'
    응답
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    친구 가져오기

    파트너 측에서 API를 실행해야 합니다. 최대 친구 수는 2000. 명입니다. 레시피를 참조하십시오.

    HTTP 요청

    GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1

    파라미터 유형 설명
    notification_type
    string 친구 목록을 가져오는 요청 유형을 정의하는 ID입니다.값은 'friends_list'입니다'.
    user
    string 기프트를 구입하는 사용자의 고유 ID.
    query
    string 친구의 이름 또는 ID(전체 또는 일부).
    limit
    string 페이지 요소 개수 제한. 필수.
    offset
    integer 목록이 생성된 요소 개수(개수는 0부터 시작함).
    sign
    string 서명 라인 생성:
    • 연결 notification_type + 키에 의해 알파벳순으로 정렬된 매개변수 값 + secret_key
    • 결과 스트링에 A-1을 적용
    Copy
    Full screen
    http
    • http
    • curl
    요청
    GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    $ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
    -X GET \
    -u merchant_id:merchant_api_key
    응답
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "friends": [
          {
            "id": "1",
            "name": "doctor",
            "email": "doctor@hospital.com",
            "image_url": "https://partner/link/doctor.jpg"
          },
          {
            "id": "2",
            "name": "cook",
            "email": "cook@kitchen.com",
            "image_url": "https://partner/link/cook.jpg"
          },
          {
            "id": "3",
            "name": "teacher",
            "email": "teacher@school.com"
          },
          {
            "id": "4",
            "name": "god",
            "email": "god@heaven.com",
            "image_url": "https://partner/link/god.jpg"
          }
          ],
        "total": 10
      }
    ]
    [
      {
      "friends": [
          {
            "id": "1",
            "name": "John Carter",
            "email": "carter@xsolla.com",
            "image_url": "https://partner/link/doctor.jpg"
          },
          {
            "id": "2",
            "name": "John Smith",
            "email": "smith@xsolla.com",
            "image_url": "https://partner/link/cook.jpg"
          }
        ],
      "total": 10
      }
    ]

    게임유저 잔액: 결제

    게임유저가 결제를 진행한 경우,게임유저 잔액 변화에 관한 특별알림 메시지를 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    operation_type
    string 작업 유형입니다.
    id_operation
    integer 엑솔라 시스템 내 작업 ID입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.email
    string 사용자 이메일.
    virtual_currency_balance
    object 시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
    virtual_currency_balance.old_value
    string 현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
    virtual_currency_balance.new_value
    string 현재 작업이 처리된 후 게임유저의 새잔액입니다.
    virtual_currency_balance.diff
    string 구매에 사용된 게임 머니 금액입니다.
    transaction
    object 트랜잭션 데이터 관련 값입니다. 필수.
    transaction.id
    integer 트랜잭션 ID입니다.
    transaction.date
    string 트랜잭션 날짜입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'transaction => array(
            'id' => '123456789',
            'date' => '2015-05-19T15:54:40+03:00'
        ),
        'operation_type' => 'payment',
        'notification_type' => 'user_balance_operation',
        'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"payment",
        "notification_type":"user_balance_operation",
        "id_operation":"66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "virtual_currency_balance":{
                "old_value":"0",
                "new_value":"200",
                "diff":"200"
            },
            "user":{
                "name":"Xsolla User",
                "id":"1234567",
                "email":"email@example.com"
            },
            "transaction":{
                "id":"123456789",
                "date":"2015-05-19T15:54:40+03:00"
            },
            "operation_type":"payment",
            "notification_type":"user_balance_operation",
            "id_operation":"66989"
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    게임유저 잔액: 구매

    게임유저가 게임 내에서 구매한 경우(예: 게임 아이템 구입) 게임유저 잔액 변화에 관한 특별 알림 메시지를 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    operation_type
    string 작업 유형입니다.
    id_operation
    integer 엑솔라 시스템 내 작업 ID입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.email
    string 사용자 이메일.
    virtual_currency_balance
    object 시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
    virtual_currency_balance.old_value
    string 현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
    virtual_currency_balance.new_value
    string 현재 작업이 처리된 후 게임유저의 새잔액입니다.
    virtual_currency_balance.diff
    string 구매에 사용된 게임 머니 금액입니다.
    items_operation_type
    string 인게임 구매의 작업 유형입니다.
    items
    array 인게임 구매 아이템 데이터와 관련된 배열입니다.
    items.sku
    string 아이템 ID입니다.
    items.amount
    integer 아이템 수량입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'virtual_currency_balance' => array(
                'old_value' => '0',
                'new_value' => '200',
                'diff' => '200'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'inGamePurchase',
        'notification_type' => 'user_balance_operation',
        'items_operation_type' =>  'add',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
        'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"inGamePurchase",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation":"66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "virtual_currency_balance":{
                "old_value":"0",
                "new_value":"200",
                "diff":"200"
            },
            "user":{
                "name":"Xsolla User",
                "id":"1234567",
                "email":"email@example.com"
            },
            "operation_type":"inGamePurchase",
            "notification_type":"user_balance_operation",
            "items_operation_type": "add",
                 "items": [{
                 "sku": "1468",
                 "amount": "2"
                 }],
            "id_operation":"66989"
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    게임유저 잔액: 쿠폰 사용

    게임유저가 쿠폰을 사용하여 아이템이나 게임머니를 구매할 경우, 이에 관한 특별 알림 메시지를 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    operation_type
    string 작업 유형입니다.
    id_operation
    integer 엑솔라 시스템 내 작업 ID입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.email
    string 사용자 이메일.
    virtual_currency_balance
    object 시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
    virtual_currency_balance.old_value
    string 현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
    virtual_currency_balance.new_value
    string 현재 작업이 처리된 후 게임유저의 새잔액입니다.
    virtual_currency_balance.diff
    string 구매에 사용된 게임 머니 금액입니다.
    items_operation_type
    string 인게임 구매의 작업 유형입니다.
    items
    array 인게임 구매 아이템 데이터와 관련된 배열입니다.
    items.sku
    string 아이템 ID입니다.
    items.amount
    integer 아이템 수량입니다.
    coupon
    object 쿠폰 데이터 관련 값입니다.
    coupon.coupon_code
    string 쿠폰 코드입니다.
    coupon.campaign_code
    string 쿠폰 캠페인 코드입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '0',
            'diff' => '0'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'coupon',
        'notification_type' => 'user_balance_operation',
        'items_operation_type' =>  'add',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
        'id_operation' => '66989',
        'coupon' =>  array(
             'coupon_code' =>  'test123',
             'campaign_code' =>  'Xsolla Campaign'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"coupon",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "virtual_currency_balance":{
                "old_value":"0",
                "new_value":"0",
                "diff":"0"
            },
            "user":{
                "name":"Xsolla User",
                "id":"1234567",
                "email":"email@example.com"
            },
            "operation_type":"coupon",
            "notification_type":"user_balance_operation",
            "items_operation_type": "add",
                 "items": [{
                     "sku": "1468",
                     "amount": "2"
                 }],
            "id_operation":"66989",
            "coupon": {
                 "coupon_code": "test123",
                 "campaign_code": "Xsolla Campaign"
            }
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    게임유저 잔액: 수동 업데이트

    게임유저 잔액을 직접 변경할 필요가 있을 경우.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    operation_type
    string 작업 유형입니다.
    id_operation
    integer 엑솔라 시스템 내 작업 ID입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.email
    string 사용자 이메일.
    virtual_currency_balance
    object 시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
    virtual_currency_balance.old_value
    string 현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
    virtual_currency_balance.new_value
    string 현재 작업이 처리된 후 게임유저의 새잔액입니다.
    virtual_currency_balance.diff
    string 구매에 사용된 게임 머니 금액입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '100',
            'diff' => '100'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'internal',
        'notification_type' => 'user_balance_operation',
        'id_operation' => '67002'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"100",
            "diff":"100"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"internal",
        "notification_type":"user_balance_operation",
        "id_operation":"67002"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "virtual_currency_balance":{
                "old_value":"0",
                "new_value":"100",
                "diff":"100"
            },
            "user":{
                "name":"Xsolla User",
                "id":"1234567",
                "email":"email@example.com"
            },
            "operation_type":"internal",
            "notification_type":"user_balance_operation",
            "id_operation":"67002"
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    게임유저 잔액: 환불

    게임유저가 결제를 취소한 경우,게임유저 잔액 변화에 관한 특별 알림 메시지를 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형입니다.
    operation_type
    string 작업 유형입니다.
    id_operation
    integer 엑솔라 시스템 내 작업 ID입니다.
    user
    object 사용자에 대한 데이터가 포함된 개체입니다.
    user.id
    string 사용자 ID. 필수.
    user.name
    string 사용자 이름.
    user.email
    string 사용자 이메일.
    virtual_currency_balance
    object 시스템 내 게임유저 잔액 데이터와 관련된 값입니다.
    virtual_currency_balance.old_value
    string 현재 작업이 처리되기 전 유저의 기존 잔액 금액입니다.
    virtual_currency_balance.new_value
    string 현재 작업이 처리된 후 게임유저의 새잔액입니다.
    virtual_currency_balance.diff
    string 구매에 사용된 게임 머니 금액입니다.
    transaction
    object 트랜잭션 데이터 관련 값입니다. 필수.
    transaction.id
    integer 트랜잭션 ID입니다.
    transaction.date
    string 트랜잭션 날짜입니다.
    items_operation_type
    string 인게임 구매의 작업 유형입니다.
    items
    array 인게임 구매 아이템 데이터와 관련된 배열입니다.
    items.sku
    string 아이템 ID입니다.
    items.amount
    integer 아이템 수량입니다.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
         'virtual_currency_balance' => array(
             'old_value' => '0',
             'new_value' => '0',
             'diff' => '0'
         ),
         'user' => array(
             'name' => 'Xsolla User',
             'id' => '1234567',
             'email' => 'email@example.com'
         ),
         'transaction' => array(
             'id' => '123456789',
             'date' => '2015-05-19T15:54:40+03:00'
         ),
         'operation_type' => 'cancellation',
         'notification_type' => 'user_balance_operation',
         'items_operation_type' =>  'remove',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
         'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"cancellation",
        "notification_type":"user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "virtual_currency_balance":{
                "old_value":"0",
                "new_value":"0",
                "diff":"0"
            },
            "user":{
                "name":"Xsolla User",
                "id":"1234567",
                "email":"email@example.com"
            },
            "transaction":{
                "id":"123456789",
                "date":"2015-05-19T15:54:40+03:00"
            },
            "operation_type":"cancellation",
            "notification_type":"user_balance_operation",
            "items_operation_type": "remove",
                 "items": [{
                     "sku": "1468",
                     "amount": "2"
                 }],
            "id_operation":"66989"
        }'
    응답
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    이차 시장: 아이템 목록 가져오기

    이차 시장에서 게임 인벤토리의 아이템 데이터를 요청하면 엑솔라는 알림 메시지를 웹훅 URL에 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형.
    project_id
    integer 프로젝트 ID.
    payload
    object 사용자 및 이차 시장 데이터가 있는 개체입니다.
    payload.user
    object 사용자 데이터가 있는 개체입니다.
    payload.user.id
    string 사용자 ID.
    payload.secondary_market
    object 이차 시장 데이터가 있는 개체입니다.
    payload.secondary_market.id
    string 이차 시장 ID.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
     'notification_type' => 'inventory_get',
     'project_id' => 1024,
     'payload' => array(
       'user' => array(
         'id' => 'username'
       ),
       'secondary_market' => array(
         'id' => '1'
       ),
     ),
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Content-Type: application/json
    Authorization: Signature sha1(body + project_secret)
    
    {
        "notification_type": "inventory_get",
        "project_id": 1024,
        "payload": {
             "user": {
                 "id": "username"
                  },
              "secondary_market": {
                  "id": "1"
              }
         }  
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -u merchant_id:merchant_api_key \
    -H 'Content-Type: application/json' \
    -d '{
        "notification_type": "inventory_get",
        "project_id": 1024,
        "payload": {
             "user": {
                 "id": "username"
              },
              "secondary_market": {
                  "id": "1"
              }
         }  
    }
    응답
    <?php
    
    $response = array(
     'user' => array(
      'id' => 'username'
      ),
      'items' => array(
       array(
        'sku' => 'sku1',
        'instance_id' => 'instance1'
        ),
        array(
         'sku' => 'sku2',
         'instance_id' => 'instance2'
        ),
      ),
    )
    
    HTTP/1.1 204
    
    {
        "user": {
            "id": "username"
        },
        "items": [
            {
                "sku": "sku1",
                "instance_id": “instance1”
            },
            {
                "sku": "sku2",
                "instance_id": “instance2”
            }
        ],
    }
    {
        "user": {
            "id": "username"
        },
        "items": [
            {
            "sku": "sku1",
            "instance_id": "instance1"
            },
            {
            "sku": "sku2",
            "instance_id": "instance2"
            }
        ],
    }

    이차 시장: 게임 아이템 불러오기

    이차 시장에서 게임 인벤토리의 아이템 데이터를 요청하면 엑솔라는 알림 메시지를 웹훅 URL에 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형.
    project_id
    integer 프로젝트 ID.
    payload
    object 사용자 및 이차 시장 데이터가 있는 개체입니다.
    payload.user
    object 사용자 데이터가 있는 개체입니다.
    payload.user.id
    string 사용자 ID.
    items
    array 아이템 데이터가 포함된 배열입니다.
    items.sku
    string 아이템 SKU.
    items.instance_id
    string 게임 내 고유한 아이템 ID입니다.
    payload.secondary_market
    object 이차 시장 데이터가 있는 개체입니다.
    payload.secondary_market.id
    string 이차 시장 ID.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
      'notification_type' => 'inventory_pull',
      'project_id' => 1024,
      'payload' => array(
        'user' => array(
          'id' => 'username'
        ),
        'items' => array(
          array(
            'sku' => 'sku1',
            'instance_id' => 'instance1'
          ),
          array(
            'sku' => 'sku2',
            'instance_id' => 'instance2'
          ),
        )
        'secondary_market' => array(
          'id' => '1'
        ),
      ),
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Content-Type: application/json
    Authorization: Signature sha1(body + project_secret)
    
    {
        "notification_type": "inventory_pull",
        "project_id": 1024,
        "payload": {
            "user": {
                "id": "username"
            },
            "items": [
                {
                    "sku": "sku1",
                    "instance_id": "instance1"
                },
                {
                    "sku": "sku2",
                    "instance_id": "instance2"
                },
            ],
            "secondary_market": {
                "id": "1"
            }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -u merchant_id:merchant_api_key \
    -H 'Content-Type: application/json' \
    -d '{
        "notification_type": "inventory_pull",
        "project_id": 1024,
        "payload": {
             "user": {
                 "id": "username"
                  },
             "items": [
                {
                    "sku": "sku1",
                    "instance_id": "instance1"
                },
                {
                    "sku": "sku2",
                    "instance_id": "instance2"
                }
              ],
              "secondary_market": {
                  "id": "1"
              }
         }  
    }
    응답
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    이차 시장: 게임 아이템 내보내기

    이차 시장에서 게임 인벤토리로 아이템을 내보내면 엑솔라는 알림 메시지를 웹훅 URL에 보냅니다.

    파라미터 유형 설명
    notification_type
    string 알림 유형.
    project_id
    integer 프로젝트 ID.
    payload
    object 사용자 및 이차 시장 데이터가 있는 개체입니다.
    payload.user
    object 사용자 데이터가 있는 개체입니다.
    payload.user.id
    string 사용자 ID.
    items
    array 아이템 데이터가 포함된 배열입니다.
    items.sku
    string 아이템 SKU.
    items.instance_id
    string 게임 내 고유한 아이템 ID입니다.
    payload.secondary_market
    object 이차 시장 데이터가 있는 개체입니다.
    payload.secondary_market.id
    string 이차 시장 ID.
    Copy
    Full screen
    php
    • php
    • http
    • curl
    요청
    <?php
    
    $request = array(
      'notification_type' => 'inventory_push',
      'project_id' => 1024,
      'payload' => array(
        'user' => array(
          'id' => 'username'
        )
        'items' => array(
          array(
            'sku' => 'sku1',
            'instance_id' => 'instance1'
          ),
          array(
            'sku' => 'sku2',
            'instance_id' => 'instance2'
          ),
        ),
        'secondary_market' => array(
          'id' => '1'
        ),
      ),
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Content-Type: application/json
    Authorization: Signature sha1(body + project_secret)
    
    {
        "notification_type": "inventory_push",
        "project_id": 1024,
        "payload": {
            "user": {
                "id": "username"
            },
            "items": [
                {
                    "sku": "sku1",
                    "instance_id": "instance1"
                },
                {
                    "sku": "sku2",
                    "instance_id": "instance2"
                }
            ],
            "secondary_market": {
                "id": "1"
            }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -u merchant_id:merchant_api_key \
    -H 'Content-Type: application/json' \
    -d '{
        "notification_type": "inventory_push",
        "project_id": 1024,
        "payload": {
             "user": {
                 "id": "username"
                  },
              "items": [
                  {
                      "sku": "sku1",
                      "instance_id": "instance1"
                  },
                  {
                      "sku": "sku2",
                      "instance_id": "instance2"
                  }
              ],
              "secondary_market": {
                   "id": "1"
              }
         }  
    }
    응답
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    웹훅 오류

    영구적 오류 코드:

    코드 메시지
    INVALID_USER 잘못된 게임유저입니다.
    INVALID_PARAMETER 잘못된 파라미터입니다.
    INVALID_SIGNATURE 잘못된 서명입니다.
    INCORRECT_AMOUNT 잘못된 금액입니다.
    INCORRECT_INVOICE 잘못된 인보이스입니다.
    HTTP/1.1 400 Bad Request
    
    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }