Rtdn Reference

RTDN Reference

Phase 0: Intent

Tell the user: "I will look up the RTDN notification type you asked about and recommend handling."

Phase 1: Locate

Map the user's question to one of the tables in Phase 2:

1. Integer code given (for example notificationType: 5): determine which notification family the user is in.
   • If the payload wraps the code in subscriptionNotification, use the Subscription Notification Types table.
   • If the payload wraps the code in oneTimeProductNotification, use the One Time Product Notification Types table.
   • If the payload has voidedPurchaseNotification, use the Voided Purchase Notification section.
   • If the payload has testNotification, use the Test Notification section.
2. Event name given (for example SUBSCRIPTION_ON_HOLD): search the Type column in the Subscription or One Time Product table.
3. Symptom given (for example "user lost access after failed payment"): match the trigger phrase in the Trigger column. Account hold and grace period map to codes 5 and 6 respectively in the subscription table.
4. Unassigned code (14, 15, 16, 21): report that the code is reserved and not emitted.

After locating the row, jump to Phase 3 for the handling guidance for that family.

Phase 2: Reference tables

RTDN Message Structure

Every RTDN message arrives as a Cloud Pub/Sub message with a base64 encoded JSON payload in the data field. The decoded JSON has this structure:

{
  "version": "1.0",
  "packageName": "com.example.app",
  "eventTimeMillis": "1234567890123",
  "subscriptionNotification": { },
  "oneTimeProductNotification": { },
  "voidedPurchaseNotification": { },
  "testNotification": { }
}

Only one notification field is present per message.

Subscription Notification Types

Notification type codes 14, 15, 16, and 21 are not assigned. Do not expect to receive these values.

Subscription notification payload:

{
  "version": "1.0",
  "notificationType": 4,
  "purchaseToken": "purchase-token-string",
  "subscriptionId": "premium_monthly"
}

One Time Product Notification Types

One time product notification payload:

{
  "version": "1.0",
  "notificationType": 1,
  "purchaseToken": "purchase-token-string",
  "sku": "remove_ads"
}

One time product notifications include the sku field (the product ID); subscription notifications include subscriptionId.

Voided Purchase Notification

Sent when a purchase is voided due to a refund, chargeback, or revocation.

{
  "purchaseToken": "purchase-token-string",
  "orderId": "GPA.1234-5678-9012-34567",
  "productType": 1,
  "refundType": 1
}

Test Notification

{
  "version": "1.0"
}

Test notifications have only a version field inside the testNotification object.

Phase 3: Recommended handling

Subscription notifications

For every subscription notification:

1. Decode the base64 data field from the Pub/Sub message.
2. Parse the DeveloperNotification and read subscriptionNotification.notificationType.
3. Extract purchaseToken and subscriptionId.
4. Call purchases.subscriptionsv2.get on the Google Play Developer API with the purchase token.
5. Apply the action from the Required Action column in the table, using the API response as the source of truth.
6. Acknowledge the Pub/Sub message.

Code-specific notes:

• Codes 4 (purchase) and 1 (recovered) require acknowledging the purchase within 3 days or Google refunds it.
• Code 3 (canceled) is not an immediate revocation. Grant access until lineItems[].expiryTime.
• Code 5 (on hold) is the revoke-now signal after a failed renewal. Code 6 (grace period) is the keep-access signal.
• Code 12 (revoked) requires immediate access revocation regardless of expiryTime.
• Codes 11, 17, 19, 22 have a Varies state; the notification flags that something changed and the API holds the new value.
• Code 8 is deprecated. New integrations should handle code 19 instead.

One time product notifications

1. Read oneTimeProductNotification.notificationType and purchaseToken.
2. Call purchases.products.get on the Google Play Developer API.
3. For code 1, verify the purchase state, grant the entitlement, then acknowledge (non-consumable) or consume (consumable) within 3 days.
4. For code 2, discard any pending record you created when the user began checkout.

Voided purchase notifications

1. Revoke access immediately for the purchaseToken.
2. Call the Voided Purchases API (purchases.voidedpurchases.list) for full details, including voidedReason and voidedSource.
3. Use productType to route to your subscription or one time product tables.
4. Use refundType to decide whether to revoke the full entitlement or only an adjusted quantity.

Test notifications

Acknowledge the Pub/Sub message without processing it as a real event. Log receipt so you can confirm your integration is wired up when you trigger a test from Play Console.

Handler pattern (applies to every RTDN)

1. Receive the Pub/Sub message.
2. Decode the base64 data field.
3. Parse the JSON DeveloperNotification.
4. Identify which notification field is present.
5. Extract the purchaseToken.
6. Call the Google Play Developer API for current state.
7. Update your database from the API response, not from the notification alone.
8. Acknowledge the Pub/Sub message.

Never rely solely on the RTDN payload for business logic. RTDNs signal that something changed. The API tells you the current state.

References

• Full chapter