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 payment.
  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. 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 payment

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.
  3. 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 Updated 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.
  2. After you receive a confirmation message for a successful test, set the Enable Subscription module toggle setting to On. A link with the required token will appear under the Sandbox URL heading.

Note
If your company has signed a License Agreement, activating this module will enable the sale of real subscriptions.

  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.

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!

Continue reading

Last updated: July 30, 2021

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!