Payments

Process players' one-time payments.

Supported Platforms

✅Yandex Games

✅VK Games

✅VK Play

✅OK Games

✅Kongregate

✅SmartMarket

✅Google Play

✅Android (alternative stores)

✅Web (custom site)

Platforms without support

❌CrazyGames

❌GamePix

❌GameDistribution

❌GameMonetize

❌WG Playground

❌PlayDeck

To check for purchase support on a platform in the SDK, use the ss.payments.isAvailable property.

JavaScript

// Checking for purchase support on a platform
if (ss.payments.isAvailable) {
    // You can make purchases
}

Unity

// Check payments on paltform
if (SS_Payments.IsPaymentsAvailable()) {
    // can show / purchase products
}

Payment Rules

Stick to payments rules.

There are two types of payments: one-time and permanent.

Example of a one-time purchase:

• Buy 1000 gold
• Buy chest
• Restore Lives

tip

One-time purchases must be consumed immediately.

An example of a permanent purchase:

• Disable ads
• VIP status
• Increase x5 reward per level

Constant purchases do not need to be consumed. As soon as the purchase is paid, it will always be visible to the user, until it is used up.

One-time purchase rules

JavaScript

// 1. Make purchase
await ss.payments.purchase({ tag: 'GOLD_1000' });

// 2. Give a reward
ss.player.add('gold', 1000);

// 3. Save player progess on server
await ss.player.sync();

// 4. Consume purchase
await ss.payments.consume({ tag: 'GOLD_1000' });

Unity

// 1. Make purchase
SS_Payments.Purchase("EXTRA_GOLD");

// 2. Give a reward
SS_Player.Add('gold', 1000);

// 3. Save player progess on server
SS_Player.Sync();

// 4. Consume purchase
SS_Payments.Consume("EXTRA_GOLD");

Permanent purchase rules

JavaScript

// 1. Make purchase
await ss.payments.purchase({ tag: 'VIP' });

// 2. Checking for purchase availability when needed
if (ss.payments.has('VIP')) {
    // do something with VIP status
}

Unity

// 1. Make purchase
SS_Payments.Purchase('VIP', OnPurchaseSuccess, OnPurchaseError);

private void OnPurchaseSuccess(string productIdOrTag){
    if(productIdOrTag == 'VIP')
        SS_Player.Set('VIP', true);
}
private void OnPurchaseError() => Debug.Log("PURCHASE: ERROR");

// 2. Checking for purchase availability when needed
if (SS_Player.GetBool('VIP')) {
    /// do something with VIP status
}

Purchase product

+1-3 Request

To purchase product, you need to pass an ID or Tag of product.

JavaScript

// Purchase by id
ss.payments.purchase({ id: 17541 });

// Purchase by tag
ss.payments.purchase({ tag: 'GOLD_1000' });

Unity

// Purchase by id
SS_Payments.Purchase("15234");

// Purchase by tag
SS_Payments.Purchase("EXTRA_GOLD");

Purchase product events

JavaScript

// Purchase success
ss.payments.on('purchase', ({ product, purchase }) => {});

/**
 * Error if purchase failed
 * @type {
 *     'player_not_found' |
 *     'empty_id_or_tag' |
 *     'product_not_found' |
 *     'purchases_not_alloved_on_platform' |
 *      undefined
 * }
 */
ss.payments.on('error:purchase', (error) => {});

Unity

public void Purchase() => SS_Payments.Purchase("EXTRA_GOLD", OnPurchaseSuccess, OnPurchaseError);

// Purchase success
private void OnPurchaseSuccess(string productIdOrTag) => Debug.Log("PURCHASE: SUCCESS: " + productIdOrTag);
// Error if purchase failed
private void OnPurchaseError() => Debug.Log("PURCHASE: ERROR");

Purchase with promises

JavaScript

const result = await ss.payments.purchase({ id: 17541 });

/**
 * Product data
 * @type {Product}
 */
result.product;

/**
 * Purchase data
 * @type {PlayerPurchase}
 */
result.purchase;

Unity

Not implemented

Consuming purchases

+1 Request

To use a purchase, you need to pass in a product ID or tag.

JavaScript

// Spending by ID
ss.payments.consume({ id: 17541 });

// Spending by Tag
ss.payments.consume({ tag: 'GOLD_1000' });

Unity

// Spending by ID
SS_Payments.Consume("15234");

// Spending by Tag
SS_Payments.Consume("EXTRA_GOLD");

Purchase spend events

JavaScript

// Successfully used
ss.payments.on('consume', ({ product, purchase }) => {});

// Error while using
ss.payments.on('error:consume', (error) => {});

Unity

public void Consume() => SS_Payments.Consume("EXTRA_GOLD", OnConsumeSuccess, OnConsumeError);

// Successfully used
private void OnConsumeSuccess(string productIdOrTag) => Debug.Log("CONSUME: SUCCESS: " + productIdOrTag);

// Error while using
private void OnConsumeError() => Debug.Log("CONSUME: ERROR");

Spending method through promises

JavaScript

const result = await ss.payments.consume({ id: 17541 });

/**
 * Product data
 * @type {Product}
 */
result.product;

/**
 * Purchase data
 * @type {PlayerPurchase}
 */
result.purchase;

Unity

Not implemented

Lists of Products and Purchases

FREE

Lists are loaded at the start of the game and are available immediately after SDK initialization.

Get the list of products:

JavaScript

ss.payments.products;

Unity

// Subscribe to events
private void OnEnable()
{
    SS_Payments.OnFetchProducts += OnFetchProducts;
    SS_Payments.OnFetchProductsError += OnFetchProductsError;
}

// Unsubscribe from events
private void OnDisable()
{
    SS_Payments.OnFetchProducts -= OnFetchProducts;
    SS_Payments.OnFetchProductsError -= OnFetchProductsError;
}

// Fetch the list of products through 
public void FetchProducts() => SS_Payments.Fetch()

// Successfully received
private void OnFetchProducts(List<FetchProducts> products)
{
    for (int i = 0; i < products.Count; i++)
    {
        Debug.Log("PRODUCT: ID: " + products[i].id);
        Debug.Log("PRODUCT: TAG: " + products[i].tag);
        Debug.Log("PRODUCT: NAME: " + products[i].name);
        Debug.Log("PRODUCT: DESCRIPTION: " + products[i].description);
        Debug.Log("PRODUCT: ICON: " + products[i].icon);
        Debug.Log("PRODUCT: ICON SMALL: " + products[i].iconSmall);
        Debug.Log("PRODUCT: PRICE: " + products[i].price);
        Debug.Log("PRODUCT: CURRENCY: " + products[i].currency);
        Debug.Log("PRODUCT: CURRENCY SYMBOL: " + products[i].currencySymbol);
        Debug.Log("PRODUCT: IS SUBSCRIPTION: " + products[i].isSubscription);
        Debug.Log("PRODUCT: PERIOD: " + products[i].period);
        Debug.Log("PRODUCT: TRIAL PERIOD: " + products[i].trialPeriod);
    }
}

// Errors by getting
private void OnFetchProductsError() => Debug.Log("FETCH PRODUCTS: ERROR");

Get the list of the player's purchases:

JavaScript

ss.payments.purchases;

Unity

// Subscribe to event
private void OnEnable()
{
    SS_Payments.OnFetchPlayerPurchases += OnFetchPlayerPurchases;
}

// Unsubscribe from event
private void OnDisable()
{
    SS_Payments.OnFetchPlayerPurchases -= OnFetchPlayerPurchases;
}

// Fetch the list of the player's purchases through 
public void FetchPlayerPurchases() => SS_Payments.Fetch();\

// Successfully received
private void OnFetchPlayerPurchases(List<FetchPlayerPurchases> purcahses)
{
    for (int i = 0; i < purcahses.Count; i++)
    {
        Debug.Log("PLAYER PURCHASES: PRODUCT TAG: " + purcahses[i].tag);
        Debug.Log("PLAYER PURCHASES: PRODUCT ID: " + purcahses[i].productId);
        Debug.Log("PLAYER PURCHASES: PAYLOAD: " + purcahses[i].payload);
        Debug.Log("PLAYER PURCHASES: CREATED AT: " + purcahses[i].createdAt);
        Debug.Log("PLAYER PURCHASES: EXPIRED AT: " + purcahses[i].expiredAt);
        Debug.Log("PLAYER PURCHASES: GIFT: " + purcahses[i].gift);
        Debug.Log("PLAYER PURCHASES: SUBSCRIBED: " + purcahses[i].subscribed);
    }
}

Getting a list of products

FREE Deprecated

JavaScript

ss.payments.fetchProducts();

Unity

SS_Payments.Fetch();

Get method via promises

JavaScript

const result = await ss.payments.fetchProducts();

// Answer result
const {
    // Grocery list
    products,
    // Player shopping list
    playerPurchases
} = result;

Unity

Not implemented

Events when getting a shopping list

JavaScript

// Successfully received
ss.payments.on('fetchProducts', (result) => {});

// Errors by getting
ss.payments.on('error:fetchProducts', (error) => {});

Unity

//Subscribe to events
private void OnEnable()
{
    SS_Payments.OnFetchProducts += OnFetchProducts;
    SS_Payments.OnFetchProductsError += OnFetchProductsError;
    SS_Payments.OnFetchPlayerPurchases += OnFetchPlayerPurchases;
}

//Unsubscribe from events
private void OnDisable()
{
    SS_Payments.OnFetchProducts -= OnFetchProducts;
    SS_Payments.OnFetchProductsError -= OnFetchProductsError;
    SS_Payments.OnFetchPlayerPurchases -= OnFetchPlayerPurchases;
}

public void Fetch() => SS_Payments.Fetch();

// Successfully received
private void OnFetchProducts(List<FetchProducts> products)
{
    for (int i = 0; i < products.Count; i++)
    {
        Debug.Log("PRODUCT: ID: " + products[i].id);
        Debug.Log("PRODUCT: TAG: " + products[i].tag);
        Debug.Log("PRODUCT: NAME: " + products[i].name);
        Debug.Log("PRODUCT: DESCRIPTION: " + products[i].description);
        Debug.Log("PRODUCT: ICON: " + products[i].icon);
        Debug.Log("PRODUCT: ICON SMALL: " + products[i].iconSmall);
        Debug.Log("PRODUCT: PRICE: " + products[i].price);
        Debug.Log("PRODUCT: CURRENCY: " + products[i].currency);
        Debug.Log("PRODUCT: CURRENCY SYMBOL: " + products[i].currencySymbol);
        Debug.Log("PRODUCT: IS SUBSCRIPTION: " + products[i].isSubscription);
        Debug.Log("PRODUCT: PERIOD: " + products[i].period);
        Debug.Log("PRODUCT: TRIAL PERIOD: " + products[i].trialPeriod);
    }
}

// Errors by getting
private void OnFetchProductsError() => Debug.Log("FETCH PRODUCTS: ERROR");

private void OnFetchPlayerPurchases(List<FetchPlayerPurchases> purcahses)
{
    for (int i = 0; i < purcahses.Count; i++)
    {
        Debug.Log("PLAYER PURCHASES: PRODUCT TAG: " + purcahses[i].tag);
        Debug.Log("PLAYER PURCHASES: PRODUCT ID: " + purcahses[i].productId);
        Debug.Log("PLAYER PURCHASES: PAYLOAD: " + purcahses[i].payload);
        Debug.Log("PLAYER PURCHASES: CREATED AT: " + purcahses[i].createdAt);
        Debug.Log("PLAYER PURCHASES: EXPIRED AT: " + purcahses[i].expiredAt);
        Debug.Log("PLAYER PURCHASES: GIFT: " + purcahses[i].gift);
        Debug.Log("PLAYER PURCHASES: SUBSCRIBED: " + purcahses[i].subscribed);
    }
}

Purchase fields

Field	Type	Description	Example
id	number	Purchase ID	115
tag	string	Optional tag to help with selection. You can use it instead of ID	VIP
name	string	Name translated into the user's language	VIP Status
description	string	Description translated into the user's language	No ads, reward x2
icon	string	Link to icon size 256x256	Link example
iconSmall	string	Link to icon size 64x64	Link example
price	number	Purchase price	199
currency	string	Currency code	YAN OK VOTE RUB SS
currencySymbol	string	Currency symbol (translated into the user's language and formatted if needed)	Voice, Voices
isSubscription	boolean	Purchase is a subscription	default false
period	number	Subscription duration in days	7, 30, 90
trialPeriod	number	The duration of the trial period in days (during this time, the user can cancel the subscription without debiting funds)	0, 3, 7, 30

Player Purchase Fields

Field	Type	Description	Example
productId	number	Purchase ID	115
payload	Object	Data from the purchase on the platform (for example, order ID or token)	{"order_id": 213}
createdAt	string	Date of purchase, format ISO 8601 UTC	2022-12-01T04:52:26+0000
gift	boolean	The purchase was a gift from the game developer	false
subscribed	boolean	Is the subscription for this purchase active?	true
expiredAt	string	Subscription end date, format ISO 8601 UTC	2022-12-01T04:52:26+0000

Error codes

Error	Error Description
player_not_found	Player not found
empty_id_or_tag	Passed empty ID or purchase tag
product_not_found	Purchase with this ID or tag was not found
purchases_not_alloved_on_platform	Purchases are not available on this site
undefined	Unexpected error (see console)

Stay in Touch

Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!