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

# Flutter SDK

> Official Zentra library for Flutter applications

The Zentra Flutter SDK provides convenient access to the Zentra API from Flutter applications (iOS, Android, Web).

<Note>
  The reviewed public HTTP surface for SDK integrations today is transfers, webhooks, virtual accounts, payments, cards, and tenant-enabled identity. Customers, wallets, and other higher-level helpers remain compatibility or draft surfaces unless your environment explicitly enables them.
</Note>

```yaml theme={null}
# pubspec.yaml
dependencies:
  zentra_flutter: ^1.0.0
```

## Configuration

Create a client in your `main.dart`:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final zentra = Zentra.withConfig(
    const ZentraConfig(
      secretKey: String.fromEnvironment('ZENTRA_API_KEY'),
      baseUrl: 'https://sandbox.api.usezentra.com',
    ),
  );
  
  runApp(MyApp(zentra: zentra));
}
```

## Resources

Access resources through your `Zentra` instance:

* `zentra.customers`: Customer management
* `zentra.payments`: Reviewed public charges, refunds, and saved payment tokens
* `zentra.transfers`: Bank transfers
* `zentra.virtualAccounts`: Virtual bank accounts
* `zentra.cards`: Card issuing
* `zentra.identity`: Tenant-enabled identity verification

## Examples

### Create a Transfer

```dart theme={null}
try {
  final transfer = await zentra.transfers.create(
    const CreateTransferParams(
      amount: 500000,
      bankCode: '058',
      accountNumber: '0123456789',
      accountName: 'Vendor Settlement Account',
      narration: 'Vendor payout',
      reference: 'TRF_12345',
      currency: 'NGN',
    ),
    idempotencyKey: 'idem_transfer_123',
  );
  print('Queued transfer: ${transfer.reference}');
} on ZentraException catch (e) {
  print('Error: ${e.message}');
}
```

### Create Charge

```dart theme={null}
final charge = await zentra.payments.charge(
  amountMinor: 500000, // ₦5,000.00
  currency: 'NGN',
  email: 'user@example.com',
  reference: 'ORD_12345',
  captureMode: 'customer_action_required',
);

final verified = await zentra.payments.verify(charge.reference);
print(verified.status);
```

## UI Integration

The checked-in Flutter wrapper is API-first. Build your own Flutter checkout UI, then pair it with reviewed charge creation, verification, and webhook handling in your backend.

```dart theme={null}
final valid = zentra.webhooks.verifySignature(payload, signature, webhookSecret);
if (!valid) {
  throw WebhookSignatureException(message: 'Invalid webhook signature');
}
```

## Error Handling

Handle errors with typed exceptions:

```dart theme={null}
try {
  await zentra.payments.verify('INVALID_REF');
} on InvalidRequestException catch (e) {
  print('Bad request: ${e.message}');
} on AuthenticationException {
  print('Check your API key');
} on ZentraException catch (e) {
  print('API error: ${e.message}');
}
```

## State Management

Works with any state management solution:

```dart theme={null}
// Provider example
class PaymentProvider extends ChangeNotifier {
  PaymentProvider(this.zentra);

  final Zentra zentra;
  Payment? _payment;
  bool _loading = false;
  
  Future<void> createCharge() async {
    _loading = true;
    notifyListeners();
    
    try {
      _payment = await zentra.payments.charge(
        amountMinor: 500000,
        currency: 'NGN',
        email: 'user@example.com',
        reference: 'ORD_12345',
        captureMode: 'customer_action_required',
      );
    } finally {
      _loading = false;
      notifyListeners();
    }
  }
}
```

## Source Code

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/zentra/zentra-flutter">
    View source code
  </Card>

  <Card title="pub.dev" icon="flutter" href="https://pub.dev/packages/zentra_flutter">
    Download package
  </Card>
</CardGroup>