결제 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
 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "currency": "USD"
24  },
25  "purchase": {
26    "subscription": {
27      "plan_id": "54321"
28    }
29  }
30}'

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

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

결제 UI가 열릴 때 결제 데이터 입력 페이지를 표시하도록 설정하려면 토큰 생성 API 호출에서 다음 매개 변수를 전달합니다.

  • 선택한 플랜의 ID와 purchase.subscription.plan_id.
  • 결제 방식 ID가 있는 settings.payment_method입니다. 관리자 페이지의 프로젝트에서 식별자 목록을 확인하려면 결제 > 결제 방식 섹션으로 이동하거나 고객 성공 관리자에게 요청합니다.
알림
첫 번째 결제와 연결된 정기 결제 요금이 포함된 플랜이 프로젝트에 설정되어 있는 경우 다음 매개 변수도 전달해야 합니다.
  • 정기 결제 플랜의 가격과 purchase.checkout.amount
  • 통화 가치와 purchase.checkout.currency
필요한 경우 사용자 정의용 추가 매개 변수를 전달하세요.
Copy
Full screen
Small screen
 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "payment_method": 1380,
24    "currency": "USD"
25  },
26  "purchase": {
27    "subscription": {
28      "plan_id": "54321"
29    }
30  }
31}'

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

클라이언트 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 목록은 관리자 페이지에서 가져올 수 있습니다.
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
 1curl -X 'POST' \
 2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
 3  -H 'accept: application/json' \
 4  -H 'Authorization: Bearer client_user_jwt'
 5
 6  {
 7    "plan_external_id": "PlanExternalId",
 8    "settings": {
 9      "ui": {
10        "size": "large",
11        "theme": "string",
12        "version": "desktop",
13        "desktop": {
14          "header": {
15            "is_visible": true,
16            "visible_logo": true,
17            "visible_name": true,
18            "type": "compact",
19            "close_button": true
20          }
21        },
22        "mobile": {
23          "mode": "saved_accounts",
24          "footer": {
25            "is_visible": true
26          },
27          "header": {
28            "close_button": true
29          }
30        },
31        "mode": "user_account"
32        }
33      },
34      "currency": "string",
35      "locale": "string",
36      "external_id": "string",
37      "payment_method": 1,
38      "return_url": "string",
39      "redirect_policy": {
40        "redirect_conditions": "none",
41        "delay": 0,
42        "status_for_manual_redirection": "none",
43        "redirect_button_caption": "string"
44      }
45    }
Copy
Full screen
Small screen
1{
2  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
3}

결제 UI를 여는 방법

페이 스테이션 임베드 사용

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

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

Copy
Full screen
Small screen
 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<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 버전).
payment_widget_ui.lightbox.width
stringLightbox 프레임 높이입니다. null인 경우, 페이 스테이션 높이에 따라 달라집니다. 기본값은 null입니다.
payment_widget_ui.lightbox.height
stringLightbox 프레임 높이입니다.null인 경우, 페이 스테이션 높이에 따라 달라집니다. 기본값은 100%입니다.
payment_widget_ui.lightbox.zIndex
integer속성에 의해 수직 스태킹 순서가 제어됩니다. 기본값은 1000입니다.
payment_widget_ui.lightbox.overlayOpacity
integer위젯 배경의 불투명도입니다(0 - 완전히 투명함, 1 - 완전히 불투명함). 기본값은 60%입니다(.6).
payment_widget_ui.lightbox.overlayBackground
string오버레이의 배경입니다. 기본 값은 #000000입니다.
payment_widget_ui.lightbox.modal
booleantrue인 경우 Lightbox 프레임을 닫을 수 없습니다. 기본값은 false입니다.
lightbox.closeByClick
booleantrue인 경우 오버레이를 클릭하면 Lightbox가 닫힙니다. 기본값은 true입니다.
lightbox.closeByKeyboard
booleantrue인 경우 ESC 키를 누르면 Lightbox가 닫힙니다. 기본값은 true입니다.
payment_widget_ui.lightbox.contentBackground
string프레임 배경 색상. 기본값은 #ffffff입니다. 이러한 색상 변경은 이를 포함하는 라이트박스 설정에만 영향을 미치며 페이 스테이션 iframe 자체에는 영향을 미치지 않음에 유의하시기 바랍니다.
payment_widget_ui.lightbox.contentMargin
string프레임 여백입니다. 기본값은 10px입니다.
payment_widget_ui.lightbox.spinner
string애니메이션 로딩 표시기의 유형입니다. xsolla 또는 round일 수 있습니다. 기본값은 xsolla입니다.
payment_widget_ui.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을 사용합니다.

이 기사가 도움이 되었나요?
감사합니다!
개선해야 할 점이 있을까요? 메시지
유감입니다
이 기사가 도움이 안 된 이유를 설명해 주세요. 메시지
의견을 보내 주셔서 감사드립니다!
메시지를 검토한 후 사용자 경험 향상에 사용하겠습니다.
마지막 업데이트: 2025년 9월 19일

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

문제 보고
콘텐츠를 항상 검토합니다. 여러분의 피드백은 콘텐츠를 개선에 도움이 됩니다.
후속 조치를 위해 이메일을 제공해 주세요
의견을 보내 주셔서 감사드립니다!
피드백을 보내는 중 문제가 발생했습니다
잠시 후 다시 시도하거나 doc_feedback@xsolla.com으로 연락해 주세요.