Installation

Overview#

The plugin puts one entitlement contract in front of two kinds of payment rail: a hosted web checkout, and the platform's own in-app purchase system on iOS and Android. A consuming app asks two questions, what is this customer entitled to and where do they manage it, and the answers are rail-neutral.

pub.dev Dependency Setup#

Add the package, then register it with dowel, which publishes the config and wires the provider and the config factory in one step:

flutter pub add magic_payments
dart run magic:dowel plugin:install magic_payments

plugin:install applies the bundled install.yaml. The two sections below show what it leaves behind, so you can check its work or do it by hand.

Service Provider Registration#

Register PaymentsServiceProvider in your app's provider list, the same way as any other Magic plugin:

import 'package:magic_payments/magic_payments.dart';

final providers = [
  // ... other providers
  (app) => PaymentsServiceProvider(app),
];

PaymentsServiceProvider runs the usual two-phase boot: register() binds one string-keyed singleton under 'payments', and boot() resolves the platform driver through the package's conditional-import factory. Neither phase requires a config file to exist for the five reads or the web rail to work. See Service Provider for the full sequence.

main.dart#

Register the published config the same way every other plugin config is registered:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Magic.init(
    configFactories: [
      () => appConfig,
      () => paymentsConfig,
    ],
  );

  runApp(MyApp());
}

The five reads and the web rail boot without a single key, so a web-only app whose factory is missing still works and payments:doctor is the only thing that notices. The store rail is different: it reads payments.revenuecat.public_sdk_key the first time it needs the SDK, so on iOS and Android an unregistered factory turns into a BillingException under the customer's finger on the purchase sheet.

See Configuration for every key and for why the store rail's key is resolved per platform.

Which Platform Gets Which Rail#

Which rail is present is decided by the package's own conditional-import factory, not by kIsWeb or Platform.is. macOS, Windows and Linux get the reads and no rail. See Rails and Drivers.

CLI Setup#

magic_payments adds payments:install, payments:configure and payments:doctor to dowel. Once the plugin is registered, check a project with:

dart run magic:dowel payments:doctor

See CLI Reference for what each command is for and which flags it takes.

Next Steps#

1. Read Configuration for the payments.* namespace.
2. Read Rails, especially the section on entitlement authority, before wiring a purchase button.
3. Read Drivers to see how a build resolves the driver it can serve and which backend endpoints the reads and writes call.

Related Documentation#

• Configuration: the payments.* keys.
• Rails: the three contracts.
• CLI Reference: the payments:* commands.
• Service Provider: what the provider binds and boots.
• Installation: installing Magic itself.