Enabling server-side payment notifications

To receive notifications about payment status changes in your app, configure, test, and enable delivery in the RuStore Console.
If your app uses the Pay SDK, you can also enable notifications for subscription events.

Before you enable notifications

• Set up your server to receive notifications from RuStore.

• Make sure your company is not blocked, monetization is enabled, and the app supports purchases.

  tip

  • How to enable monetization
  • How to create an in-app paid product

Configure notification delivery

1. Open the RuStore Console and go to your app.
2. In the left menu, select Monetization → Server notifications and click Connect.
3. Enter the URL of your server endpoint that will accept notifications.
   The address must start with https://.

Example of a valid URL

https://www.notification-payment-server.my-company.ru

4. Choose the notification type: payments, subscriptions, or both.

note

Notifications are available for:

• Payments — via BillingClient SDK or Pay SDK
• Subscriptions — via Pay SDK

tip

Notifications are available for events from both real and test subscriptions.

5. Copy and save the decryption key. You must configure this key in your server’s symmetric encryption component.

Configure notification types

In Notification type you can enable or disable server notifications for:

• Payment statuses
• Subscription events

Test notification delivery

Before enabling notifications, test your server configuration. Click Check in the Connection check row. Your server will receive a test notification.

Delivery guarantees do not apply to test notifications. You can send a test notification no more than once every 30 seconds.

The server response will be displayed in the RuStore Console. If it differs from Notification delivered successfully, verify your server configuration and network connectivity between RuStore and your server. The table below lists possible server responses.

Server response	Error	Description
HTTP status 4xx or 5xx	Not Found, Unauthorized, etc.	Text error codes are displayed according to RFC 7231.
Request timed out	Read timed out	There is a time limit for the request from RuStore to your backend. This error appears when the limit is exceeded. The limit is 3 seconds with no data written to the socket, and no more than 5 seconds total to receive a response.
Connection reset by developer’s backend	Connection reset	Your backend reset the connection.
SSL issues	Unsupported or unrecognized SSL message	SSL problem — check your server certificate.
	Name or service not known	The server address does not exist.

Enable notifications

Once you confirm that your server correctly receives notifications and returns delivery acknowledgments, enable Notify about real payments. The service will start sending notifications in real time according to the selected notification type.

Payments

Notifications are sent when a payment status changes.

Situation	Payment status change
A new payment is created (assumption)	Status becomes CREATED
The user chose a payment method in the app; payment is being executed	Status appears/changes to EXECUTED
The user cancelled the payment	Status changes to CANCELLED
Funds are reserved; the invoice awaits confirmation (consumables, two-step flow)	Status changes to PAID
Payment completed successfully	Status changes to CONFIRMED
Funds were refunded to the buyer	Status changes to REFUNDED
Authorization hold was cancelled	Status changes to REVERSED
Payment failed (insufficient funds, invalid CVC, etc.)	Status changes to REJECTED
Payment window expired	Status changes to EXPIRED
Refund initiated; request sent to the acquirer	Status changes to REFUNDING

Subscriptions

Notifications are sent when subscription state changes (activation, renewal, payment issues, or closure).

Situation	Subscription status & event
The user purchased a subscription and the first payment succeeded	subscription_event_type = ACTIVATED, subscription status becomes ACTIVE. The subscription period changes.
Subscription renewed; recurring payment succeeded	subscription_event_type = RENEWED, status remains ACTIVE. In certain cases, the subscription period changes.
The user disabled auto-renewal	subscription_event_type = CANCELLED; the subscription remains active until the paid period ends, then transitions to a final status (usually CLOSED).
The user resumed auto-renewal	subscription_event_type = RESUMED; status becomes or remains ACTIVE.
The next charge failed, subscription not closed	subscription_event_type = PAYMENT_FAILED; the subscription enters GRACE or HOLD (status may become PAUSED).
Subscription closed after auto-renewal was disabled or due to payment issues	subscription_event_type = CLOSED; status transitions to final CLOSED or TERMINATED.

If your server returns an error in response to a notification, RuStore will retry delivery. See Notification delivery guarantees.

What’s next

Right after enabling: ensure that the payload from the notification is decrypted correctly. It contains the app information, purchased product, and the new and previous statuses.

Going forward:

• During outages or maintenance, you can temporarily disable notifications.
• If your endpoint URL changes, update it in the RuStore Console.
• If the encryption key is lost or compromised, issue a new key and update it on your server.