> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payracle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK

> Official Flutter/Dart SDK for Payracle

A modern, type-safe Flutter SDK to integrate Payracle payment links, virtual accounts, and checkout interfaces into your Flutter mobile and web applications.

## Features

* **Instant Checkout Widget** — a premium centered payment modal with automated background transfer polling and countdown timers.
* **Virtual Account Provisioning** — generate persistent virtual bank accounts for your customers directly from your backend or server-side Dart services.
* **Sandbox Simulation** — test complete checkout success and failure flows using simulated payments, without moving real money.
* **Robust API Client** — complete type-safe network mapping for virtual accounts, checkouts, and transactional queries.

## Installation

Add `payracle_sdk` to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  payracle_sdk: ^0.0.2
```

Then run:

```bash theme={null}
flutter pub get
```

## Usage

### 1. Initialize the client

Configure `PayracleClient` with your public key and business ID (for client-side checkout), or your secret key (for server-side calls only):

```dart theme={null}
import 'package:payracle_sdk/payracle_sdk.dart';

final client = PayracleClient(
  apiKey: 'pk_live_your_public_key',
  businessId: 'biz_your_business_id',
);
```

<Warning>
  Only the public key (`pk_live_...` / `pk_test_...`) is safe to embed in a shipped mobile app. It can only call checkout initialization — never bundle your secret key (`sk_live_...`) into client-side app code.
</Warning>

### 2. Display the checkout sheet

```dart theme={null}
// 1. Initialize checkout session details
final checkout = await client.initializeCheckout(
  CheckoutRequest(
    amount: 1500.0,
    email: 'customer@example.com',
    title: 'Order #9928',
    description: 'Payment for running shoes',
  ),
);

// 2. Launch the centered, blurred checkout modal
await PayracleCheckoutSheet.show(
  context: context,
  client: client,
  checkoutData: checkout.data,
  onSuccess: (verifyResponse) {
    print('Payment complete: ${verifyResponse.data.reference}');
  },
  onCancelled: () {
    print('User closed checkout sheet');
  },
);
```

`PayracleCheckoutSheet` handles polling the transaction status in the background and shows a countdown timer until the generated virtual account expires — see [Checkout & Dynamic Accounts](/checkout/overview) for what happens behind this call.