# Backend Instructions for Google Play Billing Verification

## Overview

To ensure the security and integrity of in-app subscriptions, we need to perform server-side verification of all purchases made through the Google Play Store. This document outlines the requirements for the backend implementation.

## Why Server-Side Verification is Required

Client-side verification is not secure. A malicious user can decompile the app, bypass the client-side checks, and gain access to premium features without a valid subscription. Server-side verification provides a secure way to confirm that a purchase is legitimate and to reliably track the subscription status of a user.

## 1. Create a New API Endpoint

We need a new API endpoint, for example `/api/verify-purchase`, that will receive the purchase details from the app.

**Request Body:**

The app will send a POST request to this endpoint with a JSON body containing the following fields:

```json
{
  "purchaseToken": "<the purchase token from the Google Play Store>",
  "productId": "<the product ID of the purchased item>",
  "userId": "<the user ID of the user who made the purchase>"
}
```

## 2. Verify the Purchase with Google

On receiving a request, the backend server must call the Google Play Developer API to verify the purchase.

**API Endpoint:**

`https://www.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}`

**Parameters:**

*   `packageName`: The package name of the app (e.g., `com.example.app`).
*   `subscriptionId`: The product ID of the subscription (e.g., `cmdsharp_premium_monthly`).
*   `token`: The purchase token received from the app.

**Authentication:**

You will need to set up a service account in the Google Play Console and use its credentials to authenticate your requests to the Google Play Developer API. Please refer to the [Google Play Developer API documentation](https://developers.google.com/android-publisher/getting_started) for more details.

## 3. Process the Verification Response

The response from the Google Play Developer API will contain the purchase details, including the `purchaseState` and `acknowledgementState`.

*   **`purchaseState`**: `0` for purchased, `1` for canceled, `2` for pending.
*   **`acknowledgementState`**: `0` for not acknowledged, `1` for acknowledged.

Your backend should:

1.  **Check the `purchaseState`**. If it is `0` (purchased), the purchase is valid.
2.  **Check the `acknowledgementState`**. If it is `0` (not acknowledged), your backend must acknowledge the purchase. You can do this by calling another endpoint of the Google Play Developer API. **This is critical. Purchases that are not acknowledged within 3 days will be automatically refunded.**
3.  **Store the subscription status** in your database, linked to the user's account. You should store the `expiryTimeMillis` from the response to know when the subscription expires.

## 4. Respond to the App

After verifying the purchase and updating the user's subscription status in your database, the backend should send a response to the app.

**Success Response:**

```json
{
  "success": true,
  "isActive": true,
  "tier": "premium"
}
```

**Error Response:**

```json
{
  "success": false,
  "error": "Invalid purchase token"
}
```

## 5. Handle Subscription Status Updates

The backend should also handle subscription status updates, such as renewals, cancellations, and expirations. You can set up Real-Time Developer Notifications (RTDN) from the Google Play Console to receive notifications about these events.

When you receive a notification, you should update the user's subscription status in your database accordingly.

## Summary of Backend Responsibilities

1.  Create a secure endpoint to receive purchase tokens from the app.
2.  Use the Google Play Developer API to verify the purchase tokens.
3.  Acknowledge new purchases.
4.  Store and manage the subscription status of each user in a secure database.
5.  Set up RTDN to handle subscription lifecycle events.
6.  Provide an API for the app to query the current subscription status of a user.