Get subscription information

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

• request information using the API calls (suitable for serverless integration)
• get information when the subscription status changes automatically using webhooks (suitable for server-side integration)

Set up via API calls

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.

curl -X 'GET' \
  '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'

{
  "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:

• Paying for a subscription:
  • User Validation
  • Payment
  • Created Subscription

• Renewing a subscription:
  • User Validation
  • Payment
  • Updated Subscription
• Canceling a subscription: Canceled Subscription (subscription was canceled in Publisher Account or all payments were canceled for all valid periods)

• 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)

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

3. Specify your webhook URL. Click Save settings.

4. Test webhooks in Publisher Account.
5. Test subscription purchase.
6. Test subscription renewal.
7. Test subscription cancellation.

Test webhooks in Publisher Account

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

2. 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:
   • User ID
   • Xsolla Invoice ID
   • Amount
   • Currency
   • Plan ID
   • Subscription product (optional)
   • Invoice ID — internal order number (optional)
   • Trial period (To test subscription purchase in Sandbox mode or test subscription renewal, set a 0 value.)

3. Click Test.
4. 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

• Use the Sandbox mode (for subscriptions with a trial period of 0 days)
• Make a real payment and then initiate a refund via Publisher Account (for subscriptions with a trial period of more than 0 days)

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.

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

Real payment

1. Complete Testing webhooks in Publisher Account and activate the Subscriptions module.
2. Sign a License agreement.

3. Get a token for real payments.

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

7. Receive User Validation, Payment, and Updated Subscription webhooks at the webhook URL you provided in the Set up webhooks step.
8. Refund your payment. To do this, go to Publisher Account > Support > Transaction search.
9. 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

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

• Search by subscription
• Search by recent transactions
• API calls

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.

Use API calls

Open payment UI in Sandbox mode

• Use Publisher Account
• Use API call

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.

2. 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/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step.