# Magic Payments

**One entitlement contract over two billing rails.**

Multi-rail billing for apps on the Magic framework: a web rail and a store in-app-purchase rail on iOS and Android, read through the same `Payments` facade.

## One contract. Two rails.

Your app asks `Payments` what the user is entitled to, and the web rail or the store rail does the billing behind it. Each platform gets the rails it supports.

### Five entitlement reads

`currentEntitlement`, `getPlans`, `getUsage`, `getInvoices` and `getPaymentMethod` work on every platform that has a driver, e.g. `Payments.currentEntitlement()`.

[Learn more about Five entitlement reads](https://anilcancakir.com/magic/docs/payments/architecture/payments-manager.md)

### Web rail

`Payments.web` covers checkout, swap plan, cancel and a customer portal through hosted pages your backend opens. The contract is `WebBillingService`.

[Learn more about Web rail](https://anilcancakir.com/magic/docs/payments/basics/rails.md)

### Store rail

`Payments.store` runs iOS and Android purchases through RevenueCat: identify, purchase, products, restore and the store's subscription management.

[Learn more about Store rail](https://anilcancakir.com/magic/docs/payments/basics/rails.md)

### Rails are checked

`Payments.web` and `Payments.store` are nullable, so the app asks which rail it has before it shows a button.

[Learn more about Rails are checked](https://anilcancakir.com/magic/docs/payments/basics/rails.md)

### Where to manage

`manageVia` and `manageUrl` on `BillingEntitlement` say whether the user manages the plan on the web or in the store.

[Learn more about Where to manage](https://anilcancakir.com/magic/docs/payments/architecture/payments-manager.md)

### A dowel CLI

`payments:install`, `payments:configure` and `payments:doctor`, plus one read-only MCP tool, `payments_doctor`, for AI tools.

[Learn more about A dowel CLI](https://anilcancakir.com/magic/docs/payments/basics/cli.md)

## Add it in seconds

```bash
flutter pub add magic_payments
```

Or add to `pubspec.yaml`:

```yaml
dependencies:
  magic_payments: ^1.0.2
```

Or give your AI agent this prompt:

```text
Read https://anilcancakir.com/magic/docs/payments/llms.txt and install the Magic Payments package in this project.
```

## Docs

### Getting Started

- [Installation](https://anilcancakir.com/magic/docs/payments/getting-started/installation.md)
- [Configuration](https://anilcancakir.com/magic/docs/payments/getting-started/configuration.md)

### The Basics

- [Rails](https://anilcancakir.com/magic/docs/payments/basics/rails.md)
- [Drivers](https://anilcancakir.com/magic/docs/payments/basics/drivers.md)
- [CLI Reference](https://anilcancakir.com/magic/docs/payments/basics/cli.md)

### Architecture

- [Payments Manager](https://anilcancakir.com/magic/docs/payments/architecture/payments-manager.md)
- [Service Provider](https://anilcancakir.com/magic/docs/payments/architecture/service-provider.md)