결제 UI 열기 설정

프로젝트 인증 설정에 따라 결제 UI를 열기 위해 다음 중 하나를 사용할 수 있습니다.

주의
결제 UI를 열기 위한 링크 가져오기용 클라이언트 측 메소드로는 직접 가격을 관리하고 특정 사용자의 정기 결제 가격을 설정할 수 없으므로 첫 번째 결제와 연결된 정기 결제 요금이 있는 정기 결제를 판매하는 데 사용하지 마세요.
알림
사용자가 프로젝트에서 플랜을 변경하도록 허용하려면 고객 성공 매니저에게 문의하거나 csm@xsolla.com으로 이메일을 보내서 결제 UI가 제대로 작동하도록 설정하세요.

토큰 생성 서버 API 호출을 통해

  1. 토큰 가져오기를 구현하여 결제 UI를 여는 방법:
  2. 결제 UI가 열리는 방식 구현하기:

결제 방법 선택 페이지 표시 사용

결제 UI를 열었을 때 결제 방법 선택 페이지가 표시되도록 설정하려면 선택한 플랜의 ID와 함께 purchase.subscription.plan_id 매개변수를 토큰 생성 API 호출로 전달합니다. 필요한 경우 추가 사용자 정의 매개변수를 전달합니다.
알림
첫 번째 결제와 연결된 정기 결제 요금이 포함된 플랜이 프로젝트에 설정되어 있는 경우 다음 매개변수도 전달해야 합니다.
  • 정기 결제 플랜의 가격과 purchase.checkout.amount
  • 통화 가치와 purchase.checkout.currency
Copy
Full screen
Small screen
    curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
      "user":{
        "id":{
          "value": "1234567",
          "hidden": true
        },
        "email": {
          "value": "user1234@game1234.com"
        },
        "name": {
          "value": "UserName",
          "hidden": false
        }
      },
      "settings": {
        "project_id": 12345,
        "currency": "USD"
      },
      "purchase": {
        "subscription": {
          "plan_id": "54321"
        }
      }
    }'
    

    결제 방식 선택 페이지의 예시:

    결제 데이터 입력 페이지 표시 사용

    결제 UI가 열릴 때 결제 데이터 입력 페이지를 표시하도록 설정하려면 토큰 생성 API 호출에서 다음 매개변수를 전달합니다.
    • 선택한 플랜의 ID와 purchase.subscription.plan_id.
    • 결제 방식 ID가 있는 settings.payment_method입니다. 관리자 페이지의 프로젝트에서 식별자 목록을 확인하려면 페이 스테이션 > 결제 방식 섹션으로 이동하거나 고객 성공 매니저에게 요청합니다.
    알림
    첫 번째 결제와 연결된 정기 결제 요금이 포함된 플랜이 프로젝트에 설정되어 있는 경우 다음 매개변수도 전달해야 합니다.
    • 정기 결제 플랜의 가격과 purchase.checkout.amount
    • 통화 가치와 purchase.checkout.currency
    필요한 경우 사용자 정의용 추가 매개변수를 전달하세요.
    Copy
    Full screen
    Small screen
    curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
      "user":{
        "id":{
          "value": "1234567",
          "hidden": true
        },
        "email": {
          "value": "user1234@game1234.com"
        },
        "name": {
          "value": "UserName",
          "hidden": false
        }
      },
      "settings": {
        "project_id": 12345,
        "payment_method": 1380,
        "currency": "USD"
      },
      "purchase": {
        "subscription": {
          "plan_id": "54321"
        }
      }
    }'
    

    결제 데이터 입력 페이지의 예시:

    클라이언트 API 메소드를 통해

    1. 클라이언트 API 메서드를 사용하여 결제 UI를 열기 위한 링크 가져오기를 구현합니다.
    2. 결제 UI 열기를 구현하는 방법:

    결제 UI를 열기 위한 링크 가져오기용 클라이언트 메소드

    애플리케이션의 클라이언트 측에서 HTTP POST 요청을 사용하여 결제 UI 열기를 구현: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/buy

    요청에 Authorization: Bearer <client_user_jwt> 헤더를 포함해야 합니다. 여기서 <client_user_jwt>는 사용자의 JSON 웹 토큰(JWT)으로 Base64 표준에 따라 인코딩한 고유한 토큰입니다. 토큰을 받는 방법:

    프로젝트 ID를 projectId 경로 매개변수로 지정합니다. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 찾을 수 있습니다.

    country를 쿼리 매개변수로 지정합니다. ISO 3166-1 alpha-2에 따라 사용자의 국가를 두 글자 코드로 지정합니다. 이러한 설정은 로케일과 통화 선택에 영향을 줍니다. 이 매개변수를 전달하지 않으면 사용자의 IP 주소로 국가를 결정합니다.

    요청에서 전달해야 하는 매개변수:

    • plan_external_id는 결제 방식 선택 페이지에서 결제 인터페이스를 엽니다.

    결제 UI의 예시:
    결제 UI의 예시:

    요청 본문 매개변수:

    매개 변수유형설명
    plan_external_id
    string필수입니다. 정기 결제 플랜의 외부 ID입니다. 관리자 페이지 > 정기 결제 > 구독 플랜 섹션에서 확인할 수 있습니다.
    settings
    object사용자 지정 프로젝트 설정와 관련된 객체입니다.
    settings.ui
    object인터페이스 설정입니다(객체).
    settings.ui.theme
    string결제 UI 테마. default, default_dark 또는 사용자 정의 테마 ID일 수 있습니다.
    settings.ui.version
    string장치 유형입니다. desktop(기본값) 또는 mobile이 가능합니다.
    settings.ui.desktop
    object데스크톱 버전의 인터페이스 설정입니다(객체).
    settings.ui.desktop.header
    object헤더 설정 데이터와 관련된 값입니다.
    settings.ui.desktop.header.close_button
    boolean페이 스테이션 데스크톱에 닫기 버튼을 표시할지를 설정합니다. 이 버튼은 페이 스테이션을 종료하고 settings.return_url 매개 변수에 지정된 URL로 사용자를 리디렉션합니다. 기본값은 false입니다.
    settings.ui.desktop.header.is_visible
    boolean결제 UI에 헤더가 표시되는지 여부를 나타냅니다.
    settings.ui.desktop.header.type
    string헤더의 외관입니다. compact(이 경우 게임 이름과 사용자 ID는 헤더에 표시되지 않음) 혹은 normal일 수 있습니다.
    booleantrue일 경우, 로고가 헤더에 표시됩니다(먼저 고객 성공 매니저에게 이미지 파일을 제공하세요).
    settings.ui.desktop.header.visible_name
    boolean프로젝트 이름이 헤더에 표시되는지 여부를 나타냅니다.
    settings.ui.desktop.header.type
    string헤더를 표시하는 설정 방식입니다. compact(프로젝트 이름 및 사용자 ID 표지 안 함) 또는 normal (기본값)을 설정할 수 있습니다.
    settings.ui.mobile.header.close_button
    boolean페이 스테이션 모바일에 닫기 버튼을 표시할지를 설정합니다. 이 버튼은 페이 스테이션을 종료하고 settings.return_url 매개 변수에 지정된 URL로 사용자를 리디렉션합니다. 기본값은 false입니다.
    settings.ui.mode
    string페이 스테이션의 인터페이스 모드. user_account만 가능합니다. 헤더는 계정 탐색 메뉴만 포함할 수 있으며 사용자는 제품을 선택하거나 결제를 할 수 없습니다. 이 모드는 데스크톱에서만 사용 가능합니다.
    settings.currency
    string선호하는 결제 통화입니다. 3자리 ISO 4217 통화 코드입니다.
    settings.external_id
    string게임의 트랜잭션 ID 입니다. 각 사용자 결제별로 고유해야 합니다.
    settings.payment_method
    integer결제 방식 ID입니다. 결제 방식 ID 목록은 관리자 페이지에서 또는 결제 방식 가져오기 API 호출을 사용하여 가져올 수 있습니다.
    settings.return_url
    string결제 후 사용자를 리디렉션하는 페이지입니다. 매개 변수 user_id, foreigninvoice, invoice_id, status가 링크에 자동으로 추가됩니다.
    settings.redirect_policy
    object리디렉션 정책 설정입니다(객체).
    settings.redirect_policy.redirect_conditions
    string결제 후 사용자를 반환 URL로 리디렉션하는 결제 상태입니다. none, successful, successful_or_canceled 혹은 any일 수 있습니다.
    settings.redirect_policy.delay
    integer사용자가 복귀 URL로 자동 재지정된 이후 지연 시간(초).
    settings.redirect_policy.status_for_manual_redirection
    string결제 후 사용자를 반환 URL로 리디렉션하는 결제 상태입니다. none, successful, successful_or_canceled 혹은 any일 수 있습니다.
    settings.redirect_policy.redirect_button_caption
    string수동 리디렉션 버튼 텍스트입니다.
    필요한 경우 사용자 정의용 추가 매개변수를 전달하세요.
    Copy
    Full screen
    Small screen
      curl -X 'POST' \
      'https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer client_user_jwt'
      
        {
          "plan_external_id": "PlanExternalId",
          "settings": {
            "ui": {
              "size": "large",
              "theme": "string",
              "version": "desktop",
              "desktop": {
                "header": {
                  "is_visible": true,
                  "visible_logo": true,
                  "visible_name": true,
                  "type": "compact",
                  "close_button": true
                }
              },
              "mobile": {
                "mode": "saved_accounts",
                "footer": {
                  "is_visible": true
                },
                "header": {
                  "close_button": true
                }
              },
              "mode": "user_account"
              }
            },
            "currency": "string",
            "locale": "string",
            "external_id": "string",
            "payment_method": 1,
            "return_url": "string",
            "redirect_policy": {
              "redirect_conditions": "none",
              "delay": 0,
              "status_for_manual_redirection": "none",
              "redirect_button_caption": "string"
            }
          }
      
      Copy
      Full screen
      Small screen
        {
          "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
        }
        

        페이 스테이션 임베드 사용

        웹사이트 페이지에 스크립트를 추가하여 결제 UI 위젯을 엽니다. 스크립트에 대한 전체 설명은 GitHub 리포지토리에서 확인할 수 있습니다.

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

        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에서 이벤트를 받도록 해줍니다. 이러한 이벤트를 분석 시스템으로 보낼 수 있습니다. 분석 시스템에 이벤트 처리 기능을 설정하려면, 고객 성공 매니저에게 연락하거나 csm@xsolla.com으로 이메일을 보내주세요.

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

        매개 변수유형설명
        access_token
        string토큰 생성 서버 API 호출을 통해 수신하거나 클라이언트 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 - 완전히 불투명함). 기본값은 60%입니다(.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입니다.
        결제 UI 열기를 초기화하려면 이 링크 https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN을 사용합니다. 여기서 ACCESS_TOKEN토큰 생성하기 메소드로 얻은 토큰입니다. 결제 인터페이스를 여는 클라이언트 메소드를 구현할 때 이미 만들어진 링크를 가져올 수도 있습니다.
        알림
        지불 UI를 여는 경우에만 https:// 형식의 링크를 사용해야 합니다.
        테스트하려면 https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN URL을 사용하세요.
        주의
        access_token 매개 변수에 비공개 사용자 데이터가 포함되어 있습니다. 이 매개 변수를 가져오는 경우 서버 간 통신을 사용해야 합니다.

        Iframe에서

        직접 다음 메커니즘을 구현해야 합니다.

        • 장치 유형(데스크톱 또는 모바일)을 확인하고 장치 유형을 토큰의 settings.ui.version 매개 변수 내에서 전송합니다.
        • postMessage를 통해 결제 UI로부터 이벤트를 수신합니다. 이러한 이벤트를 분석 시스템으로 전송할 수 있습니다. 분석 시스템에서 이벤트 처리를 설정하려면 고객 성공 매니저에게 문의하거나 csm@xsolla.com으로 이메일을 보내 주세요.

        Iframe으로 결제 UI를 열려면 링크 https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN을 사용합니다. 여기서 ACCESS_TOKEN토큰 생성하기 메소드로 얻은 토큰입니다. 결제 인터페이스를 여는 클라이언트 메소드를 구현할 때 이미 만들어진 링크를 가져올 수도 있습니다.

        테스트 목적을 달성하려면 이 URL https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN을 사용합니다.

        새 창에서

        새 창으로 결제 UI를 열려면 링크 https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN을 사용합니다. 여기서 ACCESS_TOKEN토큰 생성하기 메소드로 얻은 토큰입니다. 결제 인터페이스를 여는 클라이언트 메소드를 구현할 때 이미 만들어진 링크를 가져올 수도 있습니다.

        테스트 목적을 달성하려면 이 URL https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN을 사용합니다.

        진행률
        의견을 보내 주셔서 감사드립니다!
        마지막 업데이트: 2024년 1월 22일

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

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