Synchronous authorizations (optional)

We provide a set of optional outbound authorization 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.

Outbound authorization should only be treated as preview or proposal of change. In the rare scenarios such as connection timeouts, network issues and system failures, a change may not be applied even after authorization is approved by partner. The actual confirmation of the change is notified via Cloud Pubsub topic and that should be treated as source of truth for subscription and purchase order related changes.

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

Authorization flows

Partners will first receive authorizeSignup to authorize subscription creation, and then receive another authorizeCharge to authorize the charge. Google will delay authorizeCharge until the end of the free trial if applicable. authorizeSignup call is made synchronously with user purchase and would only be retried by end user.

See the sample requests and responses below:

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

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

{
    "requestId": "c153c03c474d2c44",
    "subscription": {
        "partnerUserToken": "user1",
        "lineItems": [
            {
                "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
                "description": "base subscription",
                "amount": {
                    "currencyCode": "USD",
                    "amountMicros": 10000000
                },
                "state": "LINE_ITEM_STATE_NEW"
            }
        ]
    }
}

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

{
    "subscriptionId": "partnerAssignedSubscriptionId",
    "authorizationResult": "AUTHORIZATION_RESULT_AUTHORIZED"
}


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

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

{
  "requestId": "a987dsa98",
  "purchaseOrder": {
    "partnerUserToken": "user1",
    "lineItems": [
      {
        "product": "partners/partner1/products/RSG1PD.1234-5678-9101",
        "description": "base subscription",
        "amount": {
          "currencyCode": "USD",
          "amountMicros": 10000000
        },
        "servicePeriod": {
          "startTime": "2022-04-01T00:00:00Z",
          "endTime": "2022-05-01T00:00:00Z"
        }
      }
    ],
    "subscriptionDetails": {
      "subscription": "partners/partner1/subscriptions/test-partner-subscription-id",
      "purchaseOrderType": "PURCHASE_ORDER_TYPE_RENEWAL"
    }
  }
}

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

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

The partner must approve both requests for Google to fulfill the new sign up. If the partner declines authorizeCharge, the newly created subscription will be canceled.

In-app subscription add-on purchase

Partners will first receive authorizeAddon (if configured) to authorize adding new line items to an existing subscription, and then receive another authorizeCharge (if configured) to authorize the charge, potentially 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
authorizeSignup	Subscription	In-app new signup
authorizeAddon	Subscription	In-app add-on purchase
authorizeCharge	PurchaseOrder	New sign-up, monthly renewal, in-app one-time purchase

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

Configurations

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.