결제 솔루션 통합

추천을 추적하고 협력자에게 비용을 지급하려면 먼저 엑솔라 페이 스테이션을 통합해야 합니다. 요구 사항:

  1. 페이 스테이션이 성능 최적화 방문 페이지에서 통합되었습니다.
  2. 페이 스테이션은 파트너 네트워크 프로그램을 통해 트래픽을 사용하는 게임 방문 페이지에서 사용하는 유일한 결제 방법입니다.

토큰 가져오기

결제 UI를 열려면 토큰을 받아야 합니다. 토큰은 게임과 사용자에 대한 암호화된 데이터가 포함된 문자열입니다. 구매를 허용하려면 사용자를 식별하기 위해 토큰 가져오기를 구현해야 합니다.

애플리케이션의 백엔드에서 사용자 인증 토큰 가져오기를 구현해야 합니다. 이렇게 하려면 기본 HTTP 인증이 포함된 HTTP POST 요청을 사용하고 요청 본문에 필수 매개변수를 전달합니다.

API 참조
매개 변수 전체 목록을 봅니다.

토큰의 수명은 엑솔라 API를 마지막으로 호출한 후 14시간입니다. 토큰이 만료된 후 새 토큰을 받는 로직을 구현합니다. 사용자가 애플리케이션에 다시 로그인할 필요가 없도록 백그라운드에서 새 토큰을 받는 것이 좋습니다.

기본 HTTP 인증

엑솔라 API는 기본 액세스 인증을 사용합니다. 모든 API 요청에는 Authorization: Basic <your_authorization_basic_key> 헤더가 있어야 합니다. 여기에서 <your_authorization_basic_key>는 Base64 표준으로 인코딩된 판매자 ID:API 키 쌍입니다. 이러한 매개변수를 찾으려면 게시자 계정으로 이동합니다.

  • 판매자 ID 표시 위치:
    • 프로젝트 설정 > 웹훅 섹션
    • 회사 설정 > 회사 섹션
    • 게시자 계정 페이지의 브라우저 주소 표시줄에 있는 URL. 이 URL의 형식: https://publisher.xsolla.com/​판매자 ID/게시자 계정 섹션

  • API 키는 생성할 때 한 번만 게시자 계정에 표시되며 따로 저장하고 관리해야 합니다. 다음 섹션에서 새 키를 생성할 수 있습니다.
    • 회사 설정 > API 키
    • 프로젝트 설정 > API 키

주의

API 키 작업에 대한 자세한 정보는 API 참조를 확인하세요.

주요 권장 사항:

  • 본인의 공간에 생성된 API 키를 저장합니다.. 생성된 API 키는 게시자 계정에서 한 번만 볼 수 있습니다.
  • API 키를 비밀로 유지해야 합니다. 이러한 API 키는 개인 계정과 게시자 계정의 프로젝트에 대한 액세스를 제공합니다.
  • API 키는 서버에 저장해야 하며 바이너리나 프론트엔드에는 저장해선 안 됩니다.

요청 본문

요청 본문에서 다음 필수 매개변수를 전달하세요.

매개 변수유형설명
user.id
string시스템의 고유 사용자 ID.
user.email
string구매 영수증을 전송할 사용자 이메일. 매개변수를 전달하지 않으면 결제 페이지에서 이메일 입력을 위한 필수 필드가 표시됩니다.
settings.project_id
integer게임의 엑솔라 ID. 이 정보는 게시자 계정의 프로젝트 섹션에서 확인할 수 있습니다.

사용자 환경 개선을 위해 다음 매개변수를 전달할 수도 있습니다.

매개 변수유형설명
user.name
string영수증에 표시되는 사용자 화면 이름.
settings.currency
string선호하는 결제 통화.
settings.language
string인터페이스 언어.
settings.ui.size
string결제 UI 크기: small(620 x 630 px), medium(740 x 760 px), large(820 x 840 px).

사용자 인증 토큰을 가져오는 요청의 예시

Copy
Full screen
Small screen

    curl -i -X POST \
      -u 2340:ZHgbSDVP6LtAJVWu \
      https://api.xsolla.com/merchant/v2/merchants/<merchant_id>/token \
      -H 'Content-Type: application/json' \
      -d '{
        "settings": {
          "currency": "USD",
          "language": "en",
          "project_id": <project_id>,
          "ui": {
            "size": "medium"
          }
        },
        "user": {
          "email": {
            "value": "<user_email>"
          },
          "id": {
            "value": "<user_id>"
          },
          "name": {
            "value": "<user_name>"
          }
        }
      }'

    응답으로 수신한 사용자 인증 토큰의 예시

    Copy
    Full screen
    Small screen

      {
          "token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
      }

      결제 UI 열기

      알림

      엑솔라와 계약을 체결하기 전에 결제 프로세스 테스트는 샌드박스 모드에서만 가능합니다. 오류가 있는 경우 해당 설명을 참조하세요.

      샌드박스 모드에서 결제 UI를 열려면 다음 URL https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN을 사용합니다. 여기에서ACCESS_TOKEN은(는)이전 단계에서 얻은 토큰입니다.

      새 창

      새 창에서 결제 UI를 열려면 https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN URL을 사용합니다. 여기서 TOKEN는 수령한 토큰입니다.

      알림
      위의 링크를 사용하여 샌드박스 모드에서 결제 UI를 엽니다. 프로젝트 런칭 후에는 https://secure.xsolla.com/paystation2/?access_token=TOKEN URL을 사용합니다.

      다른 옵션을 사용하여 결제 UI를 열 수도 있습니다.

      • 스테이션 임베드 사용. 제한 사항: 인게임 브라우저(WebView)에서 여는 경우 문제가 발생할 수 있습니다.
      • iFrame 사용. 제한 사항: 인게임 브라우저(WebView)와 애플리케이션의 모바일 버전에서 여는 경우 문제가 발생할 수 있습니다.

      페이 스테이션 임베드

      주의
      이 방식의 결제 UI 열기는 게임 키 판매를 지원하지 않습니다. 게임 키를 판매하려면 다음 지침을 따르세요.

      예시: 동기화 스크립트 로딩

      Copy
      Full screen
      Small screen

      <script>
         var options = {
             access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
             sandbox: true //TODO please do not forget to remove this setting when going live
         };
         var s = document.createElement('script');
         s.type = "text/javascript";
         s.async = true;
         s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
         s.addEventListener('load', function (e) {
             XPayStationWidget.init(options);
         }, false);
         var head = document.getElementsByTagName('head')[0];
         head.appendChild(s);
      </script>
      
      <button data-xpaystation-widget-open>Buy Credits</button>

      페이 스테이션 임베드는 postMessage를 통해 결제 UI에서 이벤트를 받도록 해줍니다. 이러한 이벤트를 분석 시스템으로 보낼 수 있습니다. 분석 시스템에 이벤트 처리 기능을 설정하려면, 계정 관리자에게 연락하거나 am@xsolla.com로 메일을 보내 주세요.

      엑솔라 팀에서 웹사이트와의 결제 UI 통합을 간소화하는 위젯을 만들었습니다. 위젯 스크립트는 GitHub 리포지토리에서 사용할 수 있습니다.

      스크립트 초기화 매개 변수 목록:

      매개 변수유형설명
      access_token
      string토큰. API에 의해 수신됩니다. 필수.
      sandbox
      booleantrue를 설정하여 결제 프로세스를 테스트합니다. sandbox-secure.xsolla.comsecure.xsolla.com 대신 사용됩니다.
      lightbox
      object옵션 목록 관련 객체로서, Lightbox 열기에 사용할 수 있습니다(PC 버전).
      lightbox.width
      stringLightbox 프레임 높이입니다. null인 경우, 페이 스테이션 높이에 따라 달라집니다. 기본값은 null입니다.
      lightbox.height
      stringLightbox 프레임 높이입니다.null인 경우, 페이 스테이션 높이에 따라 달라집니다. 기본값은 100%입니다.
      lightbox.zIndex
      integer속성에 의해 수직 스태킹 순서가 제어됩니다. 기본값은 1000입니다.
      lightbox.overlayOpacity
      integer오버레이의 불투명도(0~1)입니다. 기본값은 .6입니다.
      lightbox.overlayBackground
      string오버레이의 배경입니다. 기본 값은 #000000입니다.
      lightbox.modal
      booleantrue인 경우 Lightbox 프레임을 닫을 수 없습니다. 기본값은 false입니다.
      lightbox.closeByClick
      booleantrue인 경우 오버레이를 클릭하면 Lightbox가 닫힙니다. 기본값은 true입니다.
      lightbox.closeByKeyboard
      booleantrue인 경우 ESC 키를 누르면 Lightbox가 닫힙니다. 기본값은 true입니다.
      lightbox.contentBackground
      string프레임 배경 색상. 기본값은 #ffffff입니다. 이러한 색상 변경은 이를 포함하는 라이트박스 설정에만 영향을 미치며 페이 스테이션 iframe 자체에는 영향을 미치지 않음에 유의하시기 바랍니다.
      lightbox.contentMargin
      string프레임 여백입니다. 기본값은 10px입니다.
      lightbox.spinner
      string애니메이션 로딩 표시기의 유형입니다. xsolla 또는 round일 수 있습니다. 기본값은 xsolla입니다.
      lightbox.spinnerColor
      string회전자의 색상입니다. 기본값에 의해 설정되지 않습니다.
      childWindow
      object페이 스테이션 UI에 포함된 하위 창에 대한 옵션입니다. 모바일 버전에 적합합니다.
      childWindow.target
      string페이 스테이션을 열 위치를 지정합니다. _blank, _self, _parent일 수 있습니다. 기본값은 _blank입니다.

      결제 인터페이스 관련하여 발생하는 이벤트는 스크립트를 통해 추적할 수 있습니다. 인터페이스 이벤트 유형에 따라 다양한 작업을 웹 페이지에서 수행할 수 있습니다.

      이벤트 목록:

      매개 변수설명
      init위젯 초기화 이벤트입니다.
      open위젯 개시 이벤트입니다.
      load결제 인터페이스(페이 스테이션)가 로딩된 후 이벤트입니다.
      close결제 인터페이스(페이 스테이션)가 닫힌 후 이벤트입니다.
      status게임유저가 상태 페이지에서 이동한 경우의 이벤트입니다.
      status-invoice게임유저가 상태 페이지에서 이동했지만 결제가 완료되지 않은 경우의 이벤트입니다.
      status-delivering게임유저가 상태 페이지에서 이동했고, 결제가 완료되었으며, 결제 알림을 보내는 중인 경우의 이벤트입니다.
      status-done게임유저가 상태 페이지에서 이동했고 결제가 성공적으로 완료된 경우의 이벤트입니다.
      status-troubled게임유저가 상태 페이지에서 이동했지만 결제에 실패한 경우의 이벤트입니다.

      결제 UI 열기를 초기화하려면 https://secure.xsolla.com/paystation3/?access_token=TOKEN링크를 사용하세요.

      알림
      결제 UI를 여는 경우에만 https:// 형식의 링크를 사용해야 합니다.

      테스트하려면 https://sandbox-secure.xsolla.com/paystation3/?access_token=TOKEN URL을 사용하세요.

      주의
      access_token 매개변수에 비공개 사용자 데이터가 포함되어 있습니다. 이 매개변수를 가져오는 경우 서버 간 통신을 사용해야 합니다.

      Iframe

      Iframe에서 결제 UI를 여는 방법:

      1. 결제 UI로부터 이벤트를 수신하기 위해 postMessage 메커니즘을 구현합니다.
      2. 결제 그룹에서 API 호출을 사용하여 주문을 생성할 때 토큰을 가져옵니다. 요청에서 전달해야 하는 항목:
        • settings.ui.version 매개변수의 장치 유형(데스크톱 혹은 모바일)
        • settings.ui.size 매개변수의 결제 UI 크기:

      페이 스테이션 크기Iframe 너비
      대(기본값)670~850px
      590~740px
      510~630px

      1. 다음 링크 https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN로 결제 UI를 엽니다. 여기서 TOKEN은 수신한 토큰입니다.

      웹훅 설정

      이벤트(예: 결제 상태 변경)에 대한 알림을 받으려면 게시자 계정에서 웹훅을 설정하세요.

      1. 게시자 계정에서 프로젝트를 엽니다.
      2. 사이드 메뉴에서 프로젝트 설정을 클릭한 후 웹훅으로 이동합니다.
      3. 웹훅 토글을 켜기로 설정합니다.
      4. 웹훅 URL을 지정합니다.
      5. 프로젝트 웹훅 서명에 사용하는 비밀 키가 기본으로 생성됩니다. 새 비밀 키를 생성하려면 새로 고침 아이콘을 클릭합니다.
      6. 설정 저장을 클릭합니다.

      다음 웹훅을 구현하는 것이 좋습니다.

      웹훅 수신 확인하려면 귀하의 서버는 반드시 다음과 함께 응답해야 합니다.

      • 메시지 본문 없이 HTTP 코드 204.
      • 지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제를 설명하는 HTTP 코드 400.

      알림
      웹훅에 대한 자세한 내용은 API 참조를 참조하세요.

      결제 처리 테스트

      샌드박스 모드를 사용하여 결제 프로세스를 테스트할 수 있습니다. 샌드박스 모드는 실제 결제 및 결제 거부를 제외한 결제 프로세스 관련 모든 기능을 지원하는 독립형 환경입니다. 토큰 입수"mode":"sandbox"를 전송하여 샌드박스에 액세스할 수 있습니다.

      알림
      엑솔라와 계약을 체결하기 전에는 샌드박스 모드에서만 결제 프로세스를 테스트할 수 있습니다.

      샌드박스 모드에서 테스트할 수 있는 결제 프로세스:

      은행 카드 결제 테스트

      1. 샌드박스 모드로 결제 UI를 엽니다.
      2. 결제 방식에서 신용/직불 카드 그룹을 선택합니다.
      3. 은행 카드 세부 정보를 입력합니다. 나머지 필드에 값을 입력합니다. 오류를 확인하기 위해 잘못된 세부 정보(카드 번호 또는 만료일)를 입력할 수도 있습니다.
      4. 지금 지불을 클릭합니다.
      테스트 카드 목록
      테스트 은행 카드 목록을 봅니다.
      알림

      카드 세부 정보 외에도 다음 조건 중 하나라도 충족하는 경우 우편번호를 지정해야 합니다.

      • 사용자의 국가가 미국 또는 캐나다입니다.
      • 은행 식별 번호(BIN)가 카드가 미국에서 발급되었음을 나타냅니다.

      유효한 우편번호(예: 12345)를 지정할 수 있습니다. 이는 판매 세율을 결정하며 결제 테스트 진행에 영향을 주지 않습니다.
      샌드박스 은행 카드 결제를 진행할 수 있는 통화: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

      주의
      일회성 구매 및 저장된 카드 테스트에 사용할 수 있는 모든 시나리오에 대한 설명을 참조하세요.

      PayPal 결제 테스트

      PayPal 계정 만들기

      결제 프로세스를 테스트하려면 PayPal 샌드박스 모드에 사용할 계정을 생성해야 합니다.

      1. PayPal 개발자 웹사이트를 엽니다.
      2. 계정에 로그인하거나 새 계정을 생성합니다.
      3. Sandbox accounts 탭으로 이동합니다.
      4. Sandbox test accounts 페이지에서 Create account를 클릭합니다.
      5. Personal (Buyer Account) 계정 유형을 선택한 후 국가를 선택합니다.
      6. Create를 클릭합니다.

      생성된 계정이 샌드박스 계정 목록에 표시됩니다.

      기존 샌드박스 계정 정보를 사용할 수도 있습니다.

      Email IDSystem Generated Password
      sb-xmxij16980134@business.example.comoi9_m_KW
      sb-p7pju16979920@business.example.com7%%p8ioS

      테스트 결제하기

      1. 샌드박스 모드로 결제 UI를 엽니다.
      2. PayPal 결제 방식을 선택합니다.
      3. Mock Response Code 필드에서 0을 입력하거나 필드를 빈 칸으로 놔둡니다.
      4. 우편 번호 필드에 5자리 숫자를 입력합니다.

      1. 지불을 클릭합니다. PayPal 계정에 로그인할 수 있는 창으로 리디렉션됩니다.
      2. 샌드박스 계정 정보를 입력합니다. Email ID는 이메일 주소이고 System Generated Password는 암호입니다. 정보 확인 방법:
        1. PayPal 개발자 웹사이트에서 본인 계정으로 로그인합니다.
        2. Sandbox accounts 탭으로 이동합니다.
        3. Sandbox test accounts 페이지에서 샌드박스 계정을 선택합니다.
        4. •••를 클릭한 후 드롭다운 목록에서 View/Edit account를 선택합니다. 모달 창이 열리면 데이터를 확인할 수 있습니다.
      3. 테스트 결제를 완료합니다.

      주의
      일회성 구매 및 저장된 PayPal 계정 테스트에 사용할 수 있는 모든 시나리오에 대한 설명을 참조하세요.

      구동

      이전 단계를 완료하면 실제로 결제하도록 설정할 수 있습니다.

      1. 엑솔라와의 라이선스 계약에 서명했는지 확인합니다.
      2. 토큰을 입수할 때 요청 본문에서 "mode":"sandbox" 매개변수를 제거합니다.
      3. https://secure.xsolla.com/paystation3/?access_token=TOKEN 링크를 사용하여 결제 UI를 엽니다.

      주의
      실제 첫 지불 이후, 엄격한 샌드박스 지불 정책이 적용됩니다. 샌드박스 모드에서의 지불은 회사 설정 > 사용자 섹션의 게시자 계정에서 지정된 사용자에 한해서만 가능합니다.
      진행률
      의견을 보내 주셔서 감사드립니다!
      마지막 업데이트: 2021년 7월 5일

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

      문제 보고
      콘텐츠를 항상 검토합니다. 여러분의 피드백은 콘텐츠를 개선에 도움이 됩니다.
      후속 조치를 위해 이메일을 제공해 주세요
      의견을 보내 주셔서 감사드립니다!