Authorization Callbacks (optional)

We provide a set of optional authorization callback APIs for partners to approve of a new subscription signup or an add-on (a.k.a new line item) purchase. Partners may need to implement this integration for certain Google products that support in-app purchases, such as Youtube TV.

An authorization callback includes a preview of change, which will only be committed after successful processing the authorization response. The committed change is notified via Cloud Pubsub topic, which is the source of truth for subscription and purchase order changes.

This section provides guidance on how to implement integration for partner-side authorizations.

Authorization flows

In-app subscription add-on purchase

Partners will first receive authorizeAddon (if enabled) to authorize adding new line items to an existing subscription, and then receive another authorizeCharge (if enabled) to authorize the add-on charge, usually with a prorated amount. Google will delay authorizeCharge until the end of the free trial if the line items uses one. authorizeAddon call is made synchronously with user purchase and would only be retried by end user.

The partner must approve both requests for Google to fulfill the add-on purchase. If the partner declines authorizeCharge, the newly added subscription line item will be deactivated.

See the sample requests and responses below:

POST https://{partner_endpoint}/v1/partners/partner1/subscriptions/sub1:authorizeAddon HTTP/1.1

Accept: application/json
Content-Type: application/json

{
    "requestId": "c153c03c474d2c44",
    "subscription": {
        "name": "partners/partner1/subscriptions/sub1",
        "partnerUserToken": "user1",
        "lineItems": [
            {
                "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
                "description": "a base subscription",
                "amount": {
                    "currencyCode": "USD",
                    "amountMicros": 20000000
                },
                "state": "LINE_ITEM_STATE_ACTIVE"
            }
        ]
    },
    "newLineItems": [
        {
          "product": "partners/partner1/products/product_addon1",
          "description": "addon subscription",
          "amount": {
            "currencyCode": "USD",
            "amountMicros":1000000
          },
          "state": "LINE_ITEM_STATE_NEW",
          "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}



POST https://{partner_endpoint}/v1/partners/partner1/purchaseorders:authorizeCharge HTTP/1.1

Accept: application/json
Content-Type: application/json
{
  "requestId": "9876",
  "purchaseOrder": {
    "partnerUserToken": "test-token",
    "lineItems": [
      {
        "product": "partners/partner1/products/product_addon1",
        "description": "addon subscription",
        "amount": {
          "currencyCode": "USD",
          "amountMicros": 670000
        },
        "servicePeriod": {
          "startTime": "2022-04-11T00:00:00Z",
          "endTime": "2022-05-01T00:00:00Z"
        }
      }
    ],
    "subscriptionDetails": {
      "subscription": "partners/partner1/subscriptions/test-partner-subscription-id",
      "purchaseOrderType": "PURCHASE_ORDER_TYPE_PRORATION"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "purchaseOrderId": "partnerAssignedPurchaseOrderId",
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}

Monthly renewal

Partners will receive a authorizeCharge call if it is configured. Upon approval, Google will charge the transaction and extend the service for the end user for another cycle. If the partner declines authorizeCharge, the existing subscription will be moved to grace period if configured or cancelled immediately if there's no grace period. During grace period Google will retry authorizeCharge call. See grace period doc for more details.

Events that can trigger outbound authorization

API	Entity	Event	sync / async
authorizeAddon	Subscription	In-app add-on purchase	Synchronous, blocking the user transaction on the client
authorizeCharge	PurchaseOrder	New sign-up, monthly renewal, in-app one-time purchase	Asynchronous, invoked asynchronously by the billing system

Note: Only Google-initiated actions will trigger outbound authorizations.

Enablement

Partners must finalize the following configurations with Google's partners team to enable the outbound authorization integration.

• The outbound authorization actions to be enabled.
• The corresponding endpoint that implements each authorization API spec.

Authentication

We use mutual TLS certificates to authenticate that both Google and partner server are trusted by each other. No additional authentication mechanism is required.

Retry Behaviors

API	Scenario	Retry strategy & limit
authorizeAddon	Any errors / non-200 response code, or an invalid response	No system retry. The end user will see an error as they make the in-app purchase.
authorizeCharge	Any errors / non-200 response code, or an invalid response	Indefinite retry with exponential backoff. It will eventually lead to escalations to Google teams after 12 attempts over approximately 2 days.
authorizeCharge	200 response with REJECT	The system will repeat the same authorizeCharge request daily as it attempts to recover the transaction during the grace period, after which, the subscription being renewed will be cancelled, or in case of an addon, it will be deactivated.