Pay Station API v2.0

Overview

The section describes methods for working with Pay Station. Use basic authentication to call methods. To open the payment UI and enable secure payments you first need to get a token.

Endpoint path: https://api.xsolla.com.

Payment UI

Open Pay Station

Pay Station is a complete payment UI that allows your users to purchase games and items on your website. To easily implement the payment UI on your website, download the following script from our CDN: link. Use this URL to integrate the script on your website. For more information please visit our GitHub repository.

Script initialization parameters:

Parameter Type Description
access_token
string Token, received via API. Required.
sandbox
boolean Set to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com.
lightbox
object Lightbox parameters (object; desktop version only).
lightbox.width
string Lightbox frame width. If null, depends on Pay Station width. Default is null.
lightbox.height
string Lightbox frame height. If null, depends on Pay Station height. Default is ‘100%’.
lightbox.zIndex
integer Defines arrangement order. Default is 1000.
lightbox.overlayOpacity
integer Overlay opacity (0 to 1). Default is ‘.6’.
lightbox.overlayBackground
string Overlay background color. Default is ‘#000000’.
lightbox.modal
boolean If true, the lightbox frame cannot be closed. Default is ‘false’.
lightbox.closeByClick
boolean If true, clicking the overlay will close the lightbox. Default is ‘true’.
lightbox.closeByKeyboard
boolean If true, pressing ESC will close the lightbox. Default is ‘true’.
lightbox.contentBackground
string Frame background color. Default is ‘#ffffff’.
lightbox.contentMargin
string Frame margin. Default is ‘10px’.
lightbox.spinner
string Type of animated loading indicator. Can be ‘xsolla’ or ‘round’. Default is ‘xsolla’.
lightbox.spinnerColor
string Spinner color. No default value.
childWindow
object Options for the child window containing the Pay Station UI. Supported in the mobile version.
childWindow.target
string Where to open the Pay Station window. Can be ‘_blank’, ‘_self’, ‘_parent’. Default is ‘_blank’.

The script allows you to track payment UI events. Depending on the event type, you can perform various actions on the web page.

List of events:

Parameter Description
init Widget initialized.
open Widget opened.
load Payment UI (Pay Station) loaded.
close Payment UI (Pay Station) closed.
status User is on the status page.
status-invoice User is on the status page; payment in progress.
status-delivering Event when the user was moved on the status page, payment was completed, and we’re sending payment notification.
status-done User is on the status page; payment credited to the user’s account.
status-troubled Event when the user was moved on the status page, but the payment failed.

If you want to initialize the opening of the payment UI by yourself, use this link: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Notice: Parameter access_token contains private user data. Please make sure that you use server-to-server communication when getting this parameter.
Copy
Full screen
  • php
  • html
Asynchronous script loading with a callback
<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>

Test Cards List

In the Sandbox you can use these cards to simulate successful payments:

Card 3-D Secure
Card number: 4111111111111111
Exp. date: 1220
CVV2: 123
Card type: VISA
No
Card number: 5555555555554444
Exp. date: 1119
CVV2: 321
Card type: MasterCard
No
Card number: 4000000000000010
Exp. date: 1220
CVV2: 123
Card type: VISA
Yes
Card number: 5200000000000114
Exp. date: 1119
CVV2: 321
Card type: MasterCard
Yes
Card number: 6759649826438453
Exp. date: 1225
CVV2: 321
Card type: Maestro
Yes

In addition, you can use the following data to simulate declined transactions:

Card 3-D Secure Description
Card number: 4000000000000002
Exp. date: 1220
CVV2: 123
Card type: VISA
No Insufficient funds
Card number: 5200000000000007
Exp. date: 1119
CVV2: 321
Card type: MasterCard
No Insufficient funds
Card number: 4000000000000036
Exp. date: 1220
CVV2: 123
Card type: VISA
Yes Declined
Card number: 5200000000000031
Exp. date: 1119
CVV2: 321
Card type: MasterCard
Yes Declined

Errors List

Code Description
0004-0001 Token expired or incorrect.
0004-0008 Wrong URL (trying to access sandbox mode at secure.xsolla.com or live mode at sandbox-secure.xsolla.com).
0002-0004 Agreement not signed.
0004-0010 Tokenless integration prohibited.
0010-0001 Package not found.
0010-0003 Package has no DRM configured.
1000-0003 No modules turned on for the project.

Tokenization

Get Saved Accounts

Lists saved payment accounts of a given user.

HTTP REQUEST

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

Parameter Type Description
project_id
integer Project ID.
user_id
integer User ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?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
Response
<?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"
        }
    }
]

Charge With Saved Account

Charges a user via a saved payment account.

HTTP REQUEST

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

Parameter Type Description
project_id
integer Project ID. Required.
user_id
integer User ID. Required.
type
string Type of payment account: card / PayPal. Required.
account_id
integer ID of the saved account in Xsolla database. Required.
user
object User details (object).
user.ip
string User IP address. Required.
user.name
string Username.
purchase
object Object containing purchase details.
purchase.virtual_currency
object Object containing virtual currency details.
purchase.virtual_currency.quantity
float Purchase amount in the virtual currency.
purchase.checkout
object Object containing checkout details.
purchase.checkout.currency
string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
float Purchase amount.
settings
object Object containing purchase settings.
settings.mode
string Set to “sandbox” to test out the payment process. Remove the parameter for real payments.
Copy
Full screen
  • php
  • http
  • curl
Request
<?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"
    }
}'
Response
<?php

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

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

Delete Saved Account

Deletes a saved payment account.

HTTP REQUEST

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

Parameter Type Description
project_id
integer Project ID.
user_id
integer User ID.
type
string Type of payment account: card / PayPal.
account_id
integer ID of the saved account in Xsolla database.
Copy
Full screen
  • php
  • http
  • curl
Request
<?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
Response
<?php

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