Before you start, your server must be able to create sessions and your dashboard must have a return target registered. If you have not done that yet, read Dashboard setup and Server integration first.

Requirements

Install

# pubspec.yaml
dependencies:
  yallapay_flutter: ^0.1.0

Then flutter pub get. The native SDKs are pulled in by the plugin's own Gradle and CocoaPods configuration; you add nothing else.

Declare your return scheme

Checkout returns the customer to your app through a custom URL scheme. Choose one unique to your brand and declare it on each platform. This is the only platform-specific step.

Android — android/app/build.gradle:

android {
    defaultConfig {
        manifestPlaceholders = [yallapayReturnScheme: "myapp"]
    }
}

Kotlin DSL build files use manifestPlaceholders["yallapayReturnScheme"] = "myapp". The native SDK's manifest registers the receiving activity; you do not edit AndroidManifest.xml.

iOS — ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Register the same scheme against your merchant account under Apps & Return URLs, and use myapp://yallapay/return as the return URL when your server creates sessions. Unregistered schemes are rejected at session creation. The host part is always yallapay.

Configure

Await configure once, before the first payment. The natural place is main():

import 'package:flutter/foundation.dart';
import 'package:yallapay_flutter/yallapay_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await YallaPay.configure(
    publishableKey: kReleaseMode ? 'pk_live_…' : 'pk_test_…',
    returnUrl: 'myapp://yallapay/return',
    environment: kReleaseMode ? YallaPayEnvironment.live : YallaPayEnvironment.sandbox,
  );

  runApp(const MyApp());
}

Take a payment

Ask your server for a session id, then hand it to the SDK. The future completes when the customer finishes, cancels, or something fails.

Future<void> payOrder(String orderId) async {
  final sessionId = await api.createPaymentSession(orderId);   // your backend

  final result = await YallaPay.pay(sessionId);

  switch (result) {
    case PaymentCompleted(:final transactionId, :final paymentMethod):
      showPaid(transactionId, paymentMethod);
    case PaymentCanceled():
      showCancelled();
    case PaymentFailed(:final error):
      showError(error);
  }
}

What pay does, in order:

1. Reads the session with your publishable key. If it is already paid, expired or failed, returns straight away without opening anything.
2. Remembers the session id on the device, so an interrupted payment can be recovered on the next launch.
3. Opens checkout: a bottom-sheet Custom Tab on Android, a system web sheet on iOS.
4. Waits for the return deep link or for the customer to close the sheet.
5. Reads the session again and returns a result based on what the API says, never on the redirect.
6. Forgets the remembered session id.

Call it from a widget that is mounted. Disable your Pay button while the future is pending; a second call during a payment is not supported.

Handling the result

void showError(YallaPayError error) {
  if (error.isIndeterminate) {
    // A network error after checkout: the payment may have succeeded. Re-check, don't say "failed".
    scheduleRecheck();
    return;
  }
  switch (error.code) {
    case YallaPayErrorCode.paymentFailed:  showSnack('Your card was declined. Please try another.');
    case YallaPayErrorCode.sessionExpired: startNewSession();
    default:                               showSnack(error.message);
  }
}

Whatever the app shows, ship the order from your server on the webhook. See Webhooks & fulfilment.

Interrupted payments

Both operating systems can terminate your app while the customer is in the checkout sheet. When that happens the future returned by pay is gone, and the customer may have paid. The plugin keeps the in-flight session id on the device for this case. On every cold start, check for one and resolve it:

// After configure(), on every launch
final pending = await YallaPay.pendingSessionId();
if (pending != null) {
  final result = await YallaPay.sessionStatus(pending);
  if (result case PaymentCompleted(:final transactionId)) {
    showPaid(transactionId);                 // and refresh the order from your server
  }
}

• pendingSessionId() returns the interrupted session id, or null on almost every launch. It never throws, even on platforms without the plugin.
• sessionStatus reads the session from the API and returns the same three results as pay, without opening anything. It also clears the pending id.

What the customer sees

Checkout is a YallaPay-hosted page. On Android it appears as a Chrome Custom Tab in bottom-sheet form, coloured with your app's primary colour, draggable to full height. On iOS it appears as a system web-authentication sheet. In both cases the customer sees your business name, the purpose, the amount, Apple Pay or Google Pay where supported, and a card form. Card numbers are entered on the YallaPay page, never in your app, and 3-D Secure happens inside the same sheet. A small line shows the YallaPay domain; that is a platform security requirement.

Error codes

Reference

There is deliberately no method to create a session. Creating one needs your secret key, and a secret key inside an app bundle is a secret key in everyone's hands.

Supported platforms

Sample app

The package includes a one-screen example under example/: a text field for a session id, a Pay button and the launch-time recovery check. Set your publishable key in example/lib/main.dart, run flutter run on an emulator or simulator, paste a session id created against the same environment, and press Pay.

Troubleshooting

General problems, test cards and the go-live checklist are on Sandbox & go-live.