Steam wallet topup service

Below is information on how to top up a Steam wallet, i.e. add funds to a Steam account.

To learn in which countries the service is available, please contact your manager.

How to top up a wallet

Precondition

When sending a request to top up a wallet, specify an amount in RUB, after which an equivalent amount in USD will be added to the wallet.

To understand the exchange rate, regularly (for example, once an hour) send a (GET/exchange_rate) request.

This request returns an exchange rate of RUB to USD (the exchange rate is updated once an hour).

The exchange rate may vary at the moment of the actual transaction, so the USD amount added to the account might be more or less than the preestimated value.
For Russian Steam accounts this amount will be automatically converted to RUB by the exchange rate of the Steam platform.

Request example

curl -X GET \
  https://demo.smart-glocal.com/api/v1/exchange_rate \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
}'

Response example

Successful response
Unsuccessful response

{
  "rate": {
    "source_currency": "RUB",
    "destination_currency": "USD",
    "rate": 0.01,
    "active_from": "2024-10-27T02:03:00.000000Z",
    "active_to": "2024-10-27T03:03:00.000000Z"
  }
}

{
  "error": {
    "code": "string",
    "description": "string"
  }
}

Step 1. Create a session (POST/session/create)

Request example

curl -X POST \
  https://demo.smart-glocal.com/api/v1/session/create \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
  "payment_method": {
    "type": "wallet",
    "wallet": {
      "type": "steam",
      "steam": {
        "account": "nickname"
      }
    }
  },
  "amount_details": {
    "amount": 123000,
    "currency": "RUB"
  }
}'

Response example

Successful response
Unsuccessful response

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z"
  }
}

{
  "error": {
    "code": "string",
    "description": "string"
  }
}

Step 2. Start the wallet topup transaction (POST/session/start/payout)

Request example

curl -X POST \
  https://demo.smart-glocal.com/api/v1/session/start/payout \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
  "session_id": "ps_3230"
}'

Response example

Successful response
Unsuccessful response

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_1313",
        "status": "succeeded",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "wallet",
          "wallet": {
            "type": "steam",
            "steam": {
              "account": "nickname"
            }
          }
        },
        "amount_details": {
          "amount": "123000",
          "currency": "RUB"
        }
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "description": "string"
  }
}

Step 3. Wait for a webhook with the results (payment_finished)

Webhook example

{
  "type": "payment_finished",
  "session": {
    "id": "ps_3230",
    "status": "accepted",
    "created_at": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z"
  }
}

Refunds

If after a successful transaction the money is not added to the appropriate account, please contact your manager. We will refund the amount to your wallet.

How to use the API

All the data in requests to Smart Glocal and notifications from Smart Glocal is transmitted using the HTTP POST method. Message parameters are packed into a JSON object.

Server address

For testing: https://demo.smart-glocal.com
For live transactions: https://proxy.smart-glocal.com

Authentication

In the headers of your requests to Smart Glocal, always pass the following data for authentication:

your project identifier
request signature

Name	Mandatory	Type	Description
X-PARTNER-PROJECT	+	string	Project identifier (from your Smart Glocal manager)
X-PARTNER-SIGN	+	string	Request signature
X-PARTNER-SUBMERCHANT	-	string	Payer's identifier (for legal entities)

Request example with authentication

curl -X POST \
  https://demo.smart-glocal.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    // request body
}'

Request signature

The signature is needed to verify the authenticity and integrity of requests. Smart Glocal verifies that the requests received are in fact from you (and are complete); you verify Smart Glocal's notifications the same way.

To create and verify a signature, you will need a secret key and a public key. Using your public key Smart Glocal will verify signatures of your incoming payments.

Generating a key pair

You need to generate a pair of keys on your side using the RSA signature algorithm.

Creating request body signature

The signature must be transmitted together with the request to Smart Glocal. You need to sign the request body as a whole in the form in which it is sent to Smart Glocal's server (after serializing the request body into JSON to send it over HTTP).

Use your secret key for signing the request. Create a signature using the SHA-256 algorithm. The resulting signature must then be transmitted in the Base64 format.

Verifying incoming requests from Smart Glocal

All outgoing requests from Smart Glocal are signed using Smart Glocal's own secret key.

Using Smart Glocal's public key, you need to verify the signatures of the requests coming from Smart Glocal on your side. The algorithm used is SHA-256. The signature is transmitted in the Base64 format.

Smart Glocal's public keys

Signature generation and validation examples

OpenSSL
PHP

# Generating a private key
$ openssl genrsa -out private.pem 2048

# Generating a public key based on the private key
$ openssl rsa -in private.pem -pubout > public.pem

# Creating myfile.txt file contents
$ echo test > myfile.txt

# Generating a signature
$ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt

# Signature ready for transfer
$ base64 sha256.sign

# Checking the signature
$ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt
Verified OK

$data = "test";

//Obtaining the pointer to the private and public keys
$privateKey = openssl_pkey_get_private("file://private.pem");
$publicKey  = openssl_pkey_get_public("file://public.pem");

//Generating a signature based on the data using the private key
openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256);
openssl_free_key($privateKey);

//Encoding the signature into Base64 to transmit it
$base64Signature = base64_encode($signature);

//On receiving the signature, decoding it from Base64
$decodedSignature = base64_decode($base64Signature);

//Validating the received signature using the public key (success = 1)
$isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256);

Sessions and transactions

Session

All transactions are carried out within a session.

A session can have the following statuses:

created — the session has been created and is waiting to be started or canceled
in_progress — the transaction is in progress
accepted — the transaction has been completed successfully
cancelled — the transaction has been canceled
error — an unexpected error occurred while processing

Attention! This status is not final. Please contact Smart Glocal's support team and wait for a final transaction status.

Payout statuses

A payout can have the following statuses:

in_progress — the payout is being processed
pending — awaiting your confirmation (session/confirm) or cancelation (session/cancel)
succeeded — the payout has been completed successfully
failed — the payout has failed

Methods

GET/exchange_rate

Request parameters

None

Response parameters

Name	Mandatory	Type	Description
rate	+	object	Rate details
source_currency	+	string	Source currency code
destination_currency	+	string	Target currency code
rate	+	string	Exchange rate
active_from	+	string	Start of the period during which the rate is applicable
active_to	+	string	End of the period during which the rate is applicable
error	-	object	Error details
code	+	string	Error code
description	+	string	Error description

POST/session/create

Request parameters

Name	Mandatory	Type	Description
payment_method	+	object	Payout method details
type	+	string	Payout method type. Always: `wallet`
wallet	+	object	Wallet details
type	+	string	Wallet type. Always: `steam`
steam	+	object	Steam account details
account	+	string	Nickname (up to 20 characters). Make sure the nickname is correct, otherwise, the payout will fail
amount_details	+	object	Amount details
amount	+	string	Amount (min. 500RUB, max. 95000RUB). Specify the amount in minor currency units: 50000 for 500RUB
currency	+	string	Currency

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Options: `error`, `ok`
session	+	object	Session details
id	+	string	Session ID
status	+	string	Session status
created_at	+	string	Creation date in ISO 8601 format
updated_at	+	string	Update date in ISO 8601 format
error	-	object	Error details
code	+	string	Error code
description	+	string	Error description

POST/session/start/payout

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session ID

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Options: `error`, `ok`
session	+	object	Session details
id	+	string	Session ID
status	+	string	Session status
created_at	+	string	Creation date in ISO 8601 format
updated_at	+	string	Update date in ISO 8601 format
payments	+	object	Payout details
id	+	string	Session ID
status	+	string	Payout status
created_at	+	string	Creation date in ISO 8601 format
payment_method	+	object	Payout method details
type	+	string	Payout method type. Always: `wallet`
wallet	+	object	Wallet details
type	+	string	Wallet type. Always: `steam`
steam	+	object	Steam account details
account	+	string	Nickname. Make sure the nickname is correct, otherwise, the payout will fail
amount_details	+	object	Amount details
amount	+	string	Amount
currency	+	string	Currency
error	-	object	Error details
code	+	string	Error code
description	+	string	Error description

Webhooks

payment_finished

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `payment_finished`
session	+	object	Session details
id	+	string	Session ID
status	+	string	Session status
created_at	+	string	Creation date in ISO 8601 format
updated_at	+	string	Update date in ISO 8601 format

Errors

During payouts you may encounter the following errors:

rate_error — Unable to get the exchange rate
account_not_found — Unable to top up the specified account
Other errors

Sequence diagram

steamDiagram

How to top up a wallet​

Precondition​

Step 1. Create a session (POST/session/create)​

Step 2. Start the wallet topup transaction (POST/session/start/payout)​

Step 3. Wait for a webhook with the results (payment_finished)​

Refunds​

How to use the API​

Server address​

Authentication​

Request signature​

Generating a key pair​

Creating request body signature​

Verifying incoming requests from Smart Glocal​

Smart Glocal's public keys​

Sessions and transactions​

Session​

Payout statuses​

Methods​

GET/exchange_rate​

Request parameters​

Response parameters​

POST/session/create​

Request parameters​

Response parameters​

POST/session/start/payout​

Request parameters​

Response parameters​

Webhooks​

payment_finished​

Webhook parameters​

Errors​

Sequence diagram​

How to top up a wallet

Precondition

Step 1. Create a session (POST/session/create)

Step 2. Start the wallet topup transaction (POST/session/start/payout)

Step 3. Wait for a webhook with the results (payment_finished)

Refunds

How to use the API

Server address

Authentication

Request signature

Generating a key pair

Creating request body signature

Verifying incoming requests from Smart Glocal

Smart Glocal's public keys

Sessions and transactions

Session

Payout statuses

Methods

GET/exchange_rate

Request parameters

Response parameters

POST/session/create

Request parameters

Response parameters

POST/session/start/payout

Request parameters

Response parameters

Webhooks

payment_finished

Webhook parameters

Errors

Sequence diagram