Get subscription information

You can get information about activity with subscriptions in the following ways:

Set up via API calls

On the client side of your application, implement getting information about user subscriptions using an HTTP GET request.

Xsolla API uses HTTP access authentication. The request must contain a header Authorization: Bearer <client_user_jwt>, where <client_user_jwt> is a unique token encoded according to the Base64 standard. To get it:

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Specify project ID as the path parameter projectId. You can find this parameter in your Publisher Account next to the name of the project.

Specify as query parameters:

  • limit — limit for the number of elements on the page (15 elements are displayed by default).
  • offset — number of the element from which the list is generated (the count starts from 0).
  • locale — interface language (English by default). Accepts values according to the ISO 639-1 standard.

Copy
Full screen
Small screen
Request Example:
  'https://subscriptions.xsolla.com​/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

Copy
Full screen
Small screen
Response Example:
{
  "items": [
    {
      "id": 11111111,
      "plan_id": 11111,
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      },
      "period": {
        "value": 1,
        "unit": "day"
      }
    }
  ],
  "has_more": true
}

Set up webhooks

The Subscriptions solution supports webhooks for the following events:

Note
To cancel a subscription, the last payment must be canceled. If a user has renewed their subscription manually and paid for several periods, they must cancel all payments.

  • Refund:
    • Refund (payment was canceled in Publisher Account)
    • Updated Subscription (Payment was canceled, but subscription is still active. This is possible if the user accidentally paid for the subscription twice and only canceled the last payment.)
    • Canceled Subscription (payment was canceled in Publisher Account or all payments were canceled for all valid periods)

Note
You can find more information about webhooks in our API documentation.

To set up webhooks:

  1. In Publisher Account, go to Project settings > Webhooks.
  2. Set the toggle in the Webhooks block to On.

  1. Specify your webhook URL. Click Save settings.

  1. Test webhooks in Publisher Account.
  2. Test subscription purchase.
  3. Test subscription renewal.
  4. Test subscription cancellation.

Test webhooks in Publisher Account

  1. In Publisher Account > Project settings > Webhooks, go to Subscriptions tab.

  1. To test webhooks, specify values from your project (User ID, Invoice ID) to be sent in a request to the webhook URL you provided. In the absence of real values, you can enter arbitrary values. Complete the following form fields:

Note
In Publisher Account, you can only test basic User Validation and Payment webhooks. To test other webhook types, go to:

  1. Click Test.
  2. Verify that you received a test success message. If your test is successful, your server will return a 204 HTTP status code. If it is unsuccessful, your server will return either a 400 or 500 HTTP status code along with a description of the error.

Test subscription purchase

When testing a payment, User Validation, Payment, and Created Subscription webhooks will be sent to the URL you specified at the Set up webhooks step. To test the payment process, you can:

Note
Testing subscriptions with a trial period is only possible for real payments, since you cannot link a billing account to a subscription in Sandbox mode.

Sandbox mode

  1. Get a token for Sandbox mode. Pass the 0 value to the Trial period (trial_days) parameter.
  2. Choose the Credit/debit cards group of payment methods.
  3. Enter test bank card details. Enter any values in the remaining fields. You can also specify incorrect details (card number, expiration date, or CVV) in order to generate an error.

Note
In Sandbox mode you can use only test bank cards. Sandbox bank card payments can be made in the following currencies: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

  1. Receive webhooks for User Validation, Payment, and Updated Subscription at the URL you specified at the Set up webhooks step.

Real payment

To test paying for a subscription with a trial period, you’ll need to use a real payment:

  1. Complete Testing webhooks in Publisher Account and activate the Subscriptions module.
  2. Sign a License agreement. To do this, go to Publisher Account > Accounting > License agreement, complete the agreement form, and wait for confirmation.

Note
Signing the License Agreement activates the sale of real subscriptions.

  1. Get a token for real payments.

Notice
Remove the "mode":"sandbox" parameter from the token request before you start to receive real payments.

  1. Open the payment UI with the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step.
  2. Choose the Credit/debit cards group of payment methods.
  3. Enter valid bank card details.

Note
Test bank cards are suitable only for Sandbox mode. It is recommended to use Visa and MasterCard cards to test real payments.

  1. Receive User Validation, Payment, and Updated Subscription webhooks at the webhook URL you provided in the Set up webhooks step.
  2. Refund your payment. To do this, go to Publisher Account > Support > Transaction search.
  3. Choose the test transaction and click the More (•••) menu button. Click Refund in the pop-up menu (transaction should have Complete status). This will send Canceled Subscription and Refund webhooks.

Test subscription renewal

Notice
Only available for subscriptions without a trial period.

To test subscription renewal:

  1. Get a token for Sandbox mode. Pass the 0 value to the Trial period (trial_days) parameter.
  2. Pay for your subscription using any payment method.
  3. Reopen the payment interface in Sandbox mode.
  4. Pay again to renew your subscription using any payment method.
  5. Get User Validation, Payment, and Updated Subscription webhooks at the webhook URL that you specified at the Set up webhooks step.

Test subscription cancellation

To test subscription cancellation, use:

Search by subscription

  1. In Publisher Account go to Support > Subscribers.
  2. Find the subscription you want to cancel.
  3. Open the subscription status menu and select:
    1. Cancel and refund to receive Canceled Subscription and Refund webhooks.
    2. Cancel without refund to receive the Canceled Subscription webhook.

Search by recent transactions

  1. In Publisher Account, go to Support > Transaction search.
  2. Find the last transactions to be canceled.
  3. Click the More (•••) icon. Click Refund in the pop-up menu to receive the Canceled Subscription and Refund webhooks.

Note
If the subscription has been paid for several times, all payments must be canceled.

Use API calls

Use the Update Subscription API call to change the subscription status to Canceled and receive the Canceled Subscription webhook.

Open payment UI in Sandbox mode

To open the Sandbox payment UI, get a token with active sandbox mode. The following are ways to get a link with the required token:

Via Publisher account

  1. Test webhooks in Publisher Account. Specify the 0 value in the Trial period field to test a subscription that does not have a trial period. After you receive a confirmation message for a successful test, a link with the required token will appear under the Sandbox URL heading.

  1. Follow the Sandbox URL link.

Via API call

  1. Pass the "settings":{"mode":"sandbox"} parameters to Create token method. Pass the "purchase": {"subscription":{"trial_days": 0}} parameters to test a subscription that does not have a trial period.
  2. Use the following link: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step.

Your progress
Thank you for your feedback!
Last updated: November 3, 2022

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!