# Payment Recovery

> Use this skill when handling failed renewals on Android with RevenueCat. Covers how Grace Period and Account Hold are reflected in CustomerInfo automatically, when to prompt the user, and how to trigger Google's in app messaging via showInAppMessages.

- **Type:** Skill
- **Install:** `agentstack add skill-revenuecat-play-billing-skills-payment-recovery`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RevenueCat](https://agentstack.voostack.com/s/revenuecat)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [RevenueCat](https://github.com/RevenueCat)
- **Source:** https://github.com/RevenueCat/play-billing-skills/tree/main/revenuecat/payment-recovery

## Install

```sh
agentstack add skill-revenuecat-play-billing-skills-payment-recovery
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Payment Recovery

Failed renewals on Google Play move a subscription through two states: grace period (user keeps access while Google retries the card) and account hold (access revoked until the user fixes the payment method). With RevenueCat, both states land in `CustomerInfo` automatically, and Google's in app message shows by default.

## Phase 1: Understand

Three things happen when a renewal fails:

| State | Access | How RevenueCat surfaces it | User sees |
| --- | --- | --- | --- |
| Grace period | Retained | `entitlement.isActive == true` and `billingIssueDetectedAt != null` | Google in app snackbar by default |
| Account hold | Revoked | `entitlement.isActive == false` and `billingIssueDetectedAt != null` | Google in app snackbar by default |
| Recovered | Retained | `billingIssueDetectedAt == null` | Nothing |

Two signals matter in the SDK:

- `EntitlementInfo.billingIssueDetectedAt` is non null from the moment Google reports a billing problem until the user resolves it.
- `EntitlementInfo.isActive` tells you whether they still have access.

On the backend, a `BILLING_ISSUE` webhook fires once per transition. You do not decode RTDNs.

## Phase 2: Plan

Before you write app code, decide what you actually need. Most apps need none.

Ask:

1. Do you want the default Google in app message? If yes, do nothing. The SDK calls `showInAppMessagesIfNeeded` on BillingClient connect.
2. Do you want your own banner or dialog? If yes, read `billingIssueDetectedAt` from `CustomerInfo` and branch on `isActive`.
3. Do you want to gate the message to specific screens? If yes, disable the automatic call and invoke `showInAppMessagesIfNeeded(activity)` yourself.
4. Do you need a server side flag (for example, to send a recovery email)? If yes, handle the `BILLING_ISSUE` webhook. No app code required.

If you only want the default behavior, stop here.

## Phase 3: Execute

### Default (recommended)

Leave automatic in app messages on. This is the default:

```kotlin
PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(true)
    .build()
```

### Manual trigger

Disable the automatic call and show the message from your chosen activity:

```kotlin
PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(false)
    .build()

Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)
```

### Your own UI during grace period

Read the entitlement and branch on both flags:

```kotlin
val entitlement = customerInfo.entitlements["pro_access"]
when {
    entitlement == null || !entitlement.isActive ->
        showSubscribeScreen()
    entitlement.billingIssueDetectedAt != null && entitlement.isActive ->
        showGracePeriodWarning()
    entitlement.billingIssueDetectedAt != null && !entitlement.isActive ->
        showAccountHoldScreen()
    else ->
        showPremiumContent()
}
```

### Send the user to fix payment

`CustomerInfo.managementURL` points to the Google Play subscription page:

```kotlin
customerInfo.managementURL?.let { url ->
    startActivity(Intent(Intent.ACTION_VIEW, url))
}
```

## Phase 4: Verify

Test each transition:

- Use a Google Play test card that declines renewals to push a subscription into grace period.
- Confirm `entitlement.billingIssueDetectedAt` becomes non null and `isActive` stays `true`.
- Wait for account hold and confirm `isActive` flips to `false` while `billingIssueDetectedAt` remains non null.
- Update the payment method and confirm `billingIssueDetectedAt` returns to `null`.
- On backend, confirm a `BILLING_ISSUE` webhook fires on the first transition.

## References

- [Full chapter](https://www.revenuecat.com/guides/revenuecat-android-sdk/payment-recovery)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RevenueCat](https://github.com/RevenueCat)
- **Source:** [RevenueCat/play-billing-skills](https://github.com/RevenueCat/play-billing-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-revenuecat-play-billing-skills-payment-recovery
- Seller: https://agentstack.voostack.com/s/revenuecat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.