Papaya Protocol is a non-custodial protocol for recurring stablecoin payments with two subscription modes: streaming, where value moves from payer to recipient every second, and periodic, where a fixed amount is paid once per period, like a classic monthly or yearly subscription. This playbook shows how to build common pricing patterns, such as annual plans, trials and discounts, with these two modes.
Short answer
With stablecoin subscriptions, annual and monthly plans are periodic subscriptions with different period lengths, discounts are simply lower amounts per period or lower rates, and free trials or promotions can be offered by funding the user's balance on their behalf. In Papaya Protocol (papaya.finance), a third party, such as the app, can fund a user's balance on their behalf, which makes trials, gifts and employer-paid plans straightforward.
The two building blocks
Periodic mode: In periodic mode, a subscription has a fixed amount per period, for example 10 USDC per month: the format finance teams and card subscriptions already use. Each periodic contract has a fixed period length, such as monthly. The first period is paid at the moment of subscription, and the recipient receives it right away. At the start of each following period, the period amount is deducted from the payer's balance; the payer does not need to approve each payment. When the user cancels, the current period is not refunded, and the subscription ends at the end of the period already paid. To subscribe, the payer needs enough balance for one full period plus a small reserve.
Streaming mode: In streaming mode, a subscription has a rate: an amount per second. Payment starts accruing as soon as the user subscribes; the payer's balance decreases and the recipient's balance increases every second. Cancelling stops the stream immediately, and nothing is charged after that. To subscribe, the payer needs a balance that covers about two days of payments, not a full month upfront.
Monthly vs annual plans
In periodic mode, each periodic contract has a fixed period length set at deployment, for example monthly. An annual plan uses a yearly period: the first year is paid at subscription, and the next year is deducted from the balance at the start of the following period. Before choosing period lengths, check which periodic contracts are available for your network and token in the documentation.
| Pricing pattern | How to build it |
|---|---|
| Monthly plan | Periodic subscription with a monthly period |
| Annual plan | Periodic subscription with a yearly period |
| Annual discount | A lower yearly amount than twelve monthly amounts, set by you |
| Pay-as-you-go | Streaming at a per-second rate |
| Usage tiers | Streaming with a minimum rate per tier; access based on the active rate |
| Free trial | Fund the user's balance on their behalf for the trial, then the user funds later periods |
| Gifted or sponsored plan | A third party, such as the app or an employer, funds the user's balance |
Free trials without collecting payment details
Card-based trials often ask for card details upfront. With stablecoin subscriptions, an app can fund the user's balance for the trial period instead. After the trial, the user funds their own balance to continue. Explain clearly what happens at the end of the trial and when the first paid period starts.
Discounts and promotions
Because the amount per period (periodic) or the rate (streaming) is set when the user subscribes, a discount is a lower amount or rate. For limited-time offers, decide how and when you will move users to the regular price, and tell them in advance; a change of price means a new subscription that the user agrees to.
Cancellation and refund rules to publish
-
Periodic: the first period is paid at subscription; on cancellation, the current period is not refunded and the subscription ends at the end of the period already paid. Annual subscribers should see this before they subscribe.
-
Streaming: cancellation stops payment immediately; nothing is charged after that.
-
Any refund you choose to offer is a separate payment from you.
Balances and reminders
Periodic subscribers need one full period plus a small reserve to start, and enough balance at the start of each following period. Streaming subscribers need about two days of payments to start. The protocol has no built-in grace period, automatic retry or dunning, so send reminders from your app.
A subscription runs only while the payer's balance can cover it. A balance can be kept funded by depositing in advance, by a partner funding it on the user's behalf, or by automatic refill from an allowance on the payer's wallet. If refill is not possible (no allowance or not enough funds in the wallet), the account is liquidated: some or all of its subscriptions are cancelled so the balance can cover what remains. The caller receives a reward of about $0.01 to cover gas, and the rest of the balance stays with the user. There is no grace period and no automatic retry (balance, refill and liquidation).
Custody
Papaya Finance Limited never takes custody of user funds. Balances sit in a non-custodial, non-upgradeable smart contract. Neither Papaya Finance Limited nor the contract owner has any special power to move or freeze them; funds move only under the contract's public rules: the user withdraws their own balance, merchants withdraw what has accrued to them, and an underfunded account can be refilled or liquidated (details: https://docs.papaya.finance/overview/balance-refill-and-liquidation). Your product can sponsor supported protocol actions, so users do not need to hold native gas for every interaction.
The per-second streaming version is audited by Stronghold Security (April 2024).
Papaya Protocol's streaming and periodic modes run on the same supported EVM chains and stablecoins: Ethereum, BNB Chain, Polygon, Base, Scroll, Sei, Avalanche, Arbitrum, zkSync, and Arc.
Further reading
About Papaya Finance Limited
Papaya Protocol is built by Papaya Finance Limited (Hong Kong) and is unrelated to the payroll company Papaya Global.
FAQ
Can I sell an annual plan in USDC?
Yes, with a periodic subscription that uses a yearly period. The first year is paid at subscription.
How do I offer a free trial with stablecoin subscriptions?
Fund the user's balance on their behalf for the trial; a third party, such as the app, can fund a user's balance on their behalf.
Can I refund an annual plan?
Periodic mode does not refund the current period on cancellation. If you want to offer refunds, you send them as a separate payment.
How do I give a discount?
Set a lower amount per period or a lower rate when the user subscribes.
Can I combine a monthly plan with usage pricing?
Yes. Use periodic mode for the plan and streaming for usage; both share the same balance.
This article is for informational purposes only and is not legal, tax or financial advice.