페이 스테이션 API v2.0

개요

본 섹션은 페이 스테이션을 사용하여 작업하는 방법을 설명합니다. API 방식을 가져오려면 Basic Authentication을 사용하십시오. 결제 UI를 열고 안전한 결제를 활성화하려면 토큰을 가져와야 합니다.

Endpoint 경로: https://api.xsolla.com.

결제 UI

페이 스테이션 열기

엑솔라 팀은 개발자 웹 사이트와 결제 인터페이스의 연동을 단순화하기 위한 스크립트를 제공합니다. 스크립트는 저희 CDN에 위치해 있으며 이곳 에서 구할 수 있습니다. 스크립트를 개발자 웹 사이트와 연동하려면 이 URL을 사용하십시오. 자세한 내용을 알아보려면 Github 저장소 를 확인해 보십시오.

스크립트 초기화 파라미터 목록:

파라미터 유형 설명
access_token
string 토큰. API에 의해 수신됩니다. 필수.
샌드박스
boolean True를 설정하여 결제 프로세스를 테스트합니다. sandbox-secure.xsolla.comsecure.xsolla.com 대신 사용됩니다.
lightbox
object 옵션 목록 관련 객체로서, Lightbox 열기에 사용할 수 있습니다(PC 버전)
lightbox.width
string Lightbox 프레임의 너비입니다. null인 경우, 페이 스테이션 너비에 따라 달라집니다. 기본값은 null입니다.
lightbox.height
string Lightbox 프레임의 높이입니다. null인 경우, 페이 스테이션 높이에 따라 달라집니다. 기본값은 '100%'입니다.
lightbox.zIndex
integer 속성에 의해 수직 스태킹 순서가 제어됩니다. 기본값은 1000입니다.
lightbox.overlayOpacity
integer 오버레이의 불투명도(0~1)입니다. 기본값은 '.6'입니다.
lightbox.overlayBackground
string 오버레이의 배경입니다. 기본 값은 '#000000'.
lightbox.modal
boolean Lightbox 프레임을 닫을 수 없습니다. 기본값은 'false'입니다.
lightbox.closeByClick
boolean 오버레이 클릭에 의한 Lightbox 닫기를 설정/해제합니다. 기본값은 'true'입니다.
lightbox.closeByKeyboard
boolean ESC 키 누르기에 의한 Lightbox 닫기를 설정/해제합니다. 기본값은 'true'입니다.
lightbox.contentBackground
string 프레임의 배경입니다. 기본 값은 '#ffffff'.
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/paystation2/?access_token=ACCESS_TOKEN 링크를 이용하십시오.

테스트 목적을 위해 다음 URL을 사용하십시오. https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Notice: access_token 매개변수에 비공개 사용자 데이터가 포함되어 있습니다. 이 매개변수를 가져오는 경우 서버 간 통신을 사용해야 합니다.
Copy
Full screen
  • php
  • html
콜백을 통한 비동기 스크립트 로딩의 예
<html>
<head lang="en">
    <meta charset="UTF-8">
</head>
<body>
    <button data-xpaystation-widget-open>Buy Credits</button>

    <?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html>
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890'
    };
    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>

테스트 카드 목록

샌드박스 내에서 모의 결제를 해 볼 수 있는 카드는 다음과 같습니다.

카드 3-D Secure
카드 번호: 4111111111111111
만료 날짜: 12/20
CVV2: 123
카드 유형: VISA
아니
카드 번호: 5555555555554444
만료 날짜: 11/19
CVV2: 321
카드 유형: MasterCard
아니
카드 번호: 4000000000000010
만료 날짜: 12/20
CVV2: 123
카드 유형: VISA
카드 번호: 5200000000000114
만료 날짜: 11/19
CVV2: 321
카드 유형: MasterCard
카드 번호: 6759649826438453
만료 날짜: 12/25
CVV2: 321
카드 유형: Maestro

또한, 다음 데이터를 사용해 트랜잭션 거부를 시뮬레이션해 볼 수 있습니다.

카드 3-D Secure 설명
카드 번호: 4000000000000002
만료 날짜: 12/20
CVV2: 123
카드 유형: VISA
아니 불충분 한 자금
카드 번호: 5200000000000007
만료 날짜: 11/19
CVV2: 321
카드 유형: MasterCard
아니 불충분 한 자금
카드 번호: 4000000000000036
만료 날짜: 12/20
CVV2: 123
카드 유형: VISA
거부 됨
카드 번호: 5200000000000031
만료 날짜: 11/19
CVV2: 321
카드 유형: MasterCard
거부 됨

오류 목록

코드 설명
0004-0001 만료되었거나 올바르지 않은 토큰.
0004-0008 잘못된 URL (secure.xsolla.com에서 샌드박스 모드 또는 샌드박스-secure.xsolla.com에서 라이브 모드로 접근을 시도함).
0002-0004 동의서에 서명하지 않음.
0004-0010 금지된 토큰리스 통합.
0010-0001 패키지를 찾지 못함.
0010-0003 패키지에 DRM이 설정되지 않음.
1000-0003 해당 프로젝트에 대하여 활성화된 모듈이 없음.

직접 결제

저장된 결제 계정 나열

사용자의 저장된 결제 계정을 나열합니다.

HTTP 요청

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

파라미터 유형 설명
project_id
integer 프로젝트 ID.
user_id
integer 사용자 ID.
Copy
Full screen
  • php
  • http
  • curl
요청
<?php

$response = $xsollaClient->ListPaymentAccounts(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts 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/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key
응답
<?php

// example response
$response = array (
    array (
        'type' => 'card',
        'id' => 1,
        'name' => '4111110000001111',
        'payment_system' =>
            array (
                'id' => 1380,
                'name' => 'Credit/Debit Cards',
            ),
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "type": "card",
        "id": 1,
        "name": "4111110000001111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]
[
    {
        "type": "card",
        "id": 1,
        "name": "4111110000001111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

저장한 계정으로 청구

저장된 결제 계정을 사용하여 청구합니다.

HTTP 요청

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

파라미터 유형 설명
project_id
integer 프로젝트 ID. 필수.
user_id
integer 사용자 ID. 필수.
type
string 결제 계정 유형: 카드 / paypal. 필수.
account_id
integer 엑솔라 시스템의 저장된 계정에 대한 ID입니다. 필수.
user
object 사용자에 대한 데이터가 포함된 개체입니다.
user.ip
string 사용자 IP입니다. 필수.
user.name
string 사용자 이름.
purchase
object 구매 데이터 관련 값입니다.
purchase.virtual_currency
object 게임머니 데이터와 관련된 값입니다.
purchase.virtual_currency.quantity
float 게임머니 구매량입니다.
purchase.checkout
object 결제 파라미터 데이터와 관련된 값입니다.
purchase.checkout.currency
string 구매 통화입니다. 통화의 3자리 정의가 ISO 4217에 따라 사용됩니다.
purchase.checkout.amount
float 구매 금액입니다.
settings
object 구매 설정에 대한 데이터가 포함된 개체입니다.
settings.mode
string 결제 프로세스를 테스트하기 위한 "sandbox" 값을 설정합니다. 실제 결제의 경우 이 매개 변수는 제거되어야 합니다.
Copy
Full screen
  • php
  • http
  • curl
요청
<?php

$response = $xsollaClient->ChargePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID,
    'request' => array (
         'user' =>
             array (
                 'ip' => '127.0.0.1',
                 'name' => 'John Smith',
             ),
         'purchase' =>
             array (
                 'virtual_currency' =>
                     array (
                         'quantity' => 100,
                     ),
                 'description' =>
                     array (
                         'value' => 'Test Purchase',
                     ),
             ),
         'settings' =>
             array (
                 'mode' => 'sandbox',
             ),
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}'
응답
<?php

// example response
$response = array (
    'transaction_id' => 119478390
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "transaction_id": 119478390
}
{
    "transaction_id": 119478390
}

저장된 결제 계정 삭제

저장된 결제 계정 삭제.

HTTP 요청

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

파라미터 유형 설명
project_id
integer 프로젝트 ID.
user_id
integer 사용자 ID.
type
string 결제 계정 유형: 카드 / paypal.
account_id
integer 엑솔라 시스템의 저장된 계정에 대한 ID입니다.
Copy
Full screen
  • php
  • http
  • curl
요청
<?php

$response = $xsollaClient->DeletePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID
));
DELETE /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id} 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/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
응답
<?php

// example response
$response = null;
HTTP/1.1 204 No Content