Dartvel billing: subscriptions, purchases, tax and usage

Bachs charges cards in dollars or naira, and takes bank transfer and mobile money in local currencies. A sandbox key talks only to the Bachs sandbox, and a webhook is accepted while any of its current signing secrets matches, so rotating a secret drops nothing.

// What you sell, and what each plan turns on. The price is the number the
// application is held to: checkout reads the provider's own price first and
// refuses when the two disagree, so a page cannot show one price and charge
// another.
const BillingPlan team = BillingPlan(
  id: 'team',
  displayName: 'Team',
  priceMinorUnits: 4900,
  currency: 'USD',
  trialDays: 14,
);

const Entitlement reports = Entitlement('reports');

void useStripe() {
  DV.Billing.useProvider(DVStripeBillingProvider(
    secretKey: DV.Secrets.get('STRIPE_SECRET_KEY'),
    webhookSecret: DV.Secrets.get('STRIPE_WEBHOOK_SECRET'),
    // Your plan id on the left, the provider's price on the right.
    prices: const <String, String>{'team': 'price_1234'},
    // What each plan grants once the subscription is live.
    entitlements: const <String, Set<Entitlement>>{
      'team': <Entitlement>{reports},
    },
    successUrl: Uri.parse('https://example.com/billing/done'),
    cancelUrl: Uri.parse('https://example.com/pricing'),
  ));
}

Future<Uri?> subscribe(Workspace workspace) async {
  final DVBillingCheckoutSession session =
      await DV.Billing.checkout(plan: team, customer: workspace);
  // Null when the provider gave back no hosted page. Send the customer
  // nowhere; a blank tab is worse.
  return session.checkoutUrl;
}

// Asked on the server, never read off the client: the page that shows a
// feature and the code that allows it must not be two different answers.
Future<bool> mayExport(Workspace workspace) =>
    DV.Billing.hasEntitlement(workspace, reports);

DV.Purchases.buy opens StoreKit 2 on iOS and macOS and Play Billing on Android, the gateway checkout on the web and desktop. A store that writes its own invoices, such as Telegram Stars, plugs in as a store adapter from a paid runtime package.

App Store Server Notifications v2 and Play Real-time Developer Notifications are signature-checked, applied once and in order. A refund or chargeback is told apart from a lapse.

Play: the service account lives in DV.Secrets (PLAY_SERVICE_ACCOUNT_JSON), the package name and the Pub/Sub push audience under dartvel.purchases.play, and a push is believed only with Google's signed token for that audience.

dartvel build android --format aab also writes the Play Data safety answers (data-safety.csv and a worksheet) beside the bundle. It fills in only what Dartvel itself sends and lists the rest as questions for you.

// What the application sells, declared once and read by both halves.
const DVPurchaseProduct proMonthly = DVPurchaseProduct(
  'pro_monthly',
  billable: DVBillable.digital(appStore: 'com.example.pro', play: 'pro'),
  entitlements: <Entitlement>{Entitlement('pro')},
);
const DVPurchaseProduct coins = DVPurchaseProduct(
  'coins_100',
  billable: DVBillable.digital(
      appStore: 'com.example.coins', play: 'coins',
      telegram: 'coins', telegramStars: 50),
  entitlements: <Entitlement>{},
  kind: DVPurchaseKind.consumable,
);

// In the app. The store sheet on iOS and Android, the gateway checkout on
// the web and desktop: one call, no platform branch.
DVPurchases.configure(DVPurchases.device(products: <DVPurchaseProduct>[
  proMonthly,
  coins,
]));
await DV.Purchases.refreshEntitlements();

final DVPurchaseOutcome outcome = await DV.Purchases.buy(proMonthly);
switch (outcome) {
  case DVPurchaseCompleted(:final Set<String> consumed):
    creditCoins(consumed);
  case DVPurchasePending():
    showWaitingForApproval();
  case DVPurchaseCancelled() || DVPurchaseRedirected():
    break;
  case DVPurchaseFailed(:final String reason):
    showError(reason);
}

// Rebuilds when the server says what is held changed: a purchase, an Ask
// to Buy approved later, a refund at the next sync.
Widget build(BuildContext context) =>
    DV.Purchases.watch(context, const Entitlement('pro'))
        ? const ProDashboard()
        : const Upgrade();

// On the server. pubspec.yaml declares `dartvel: purchases: {}`, which
// serves /_dartvel/purchases/verify, entitlements and the stores'
// notification endpoints.
DVPurchases.configure(DVPurchases(
  products: <DVPurchaseProduct>[proMonthly, coins],
  stores: <DVStoreAdapter>[
    DVAppStoreAdapter(bundleId: 'com.example.app'),
    // The service account comes from DV.Secrets (PLAY_SERVICE_ACCOUNT_JSON);
    // the rest is `dartvel: purchases: play:` in pubspec.yaml.
    DVPlayStoreAdapter.fromSecrets(const DVPlayStoreConfig(
      packageName: 'com.example.app',
      pushAudience:
          'https://example.com/api/_dartvel/purchases/notifications/play',
      pushServiceAccount: 'play-push@example.iam.gserviceaccount.com',
    )),
  ],
  ledger: DVDatabasePurchaseLedger(DV.Database.configuredAdapter!),
  // Optional: what the web and desktop sell through.
  gateway: stripe,
  gatewayPlans: const <String, BillingPlan>{'pro_monthly': team},
));

The StoreKit 2 binding has not run on a Mac, and no purchase has gone through a real App Store or Play sandbox. The Play Billing binding has not run on an Android device, and the Play adapter has only met recorded Google responses.

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

Billing and commerce

Sell a plan through Stripe, Paddle or Bachs

Sell in-app purchases, checked on your server

Charge with tax and promotions, and refund cleanly

Meter usage and cap it per tenant