Flutter SDK

​

Introduction

Integrate Atoa into your Flutter app in minutes using our dedicated SDK.

Easily add seamless Pay by Bank payments to new or existing Flutter apps. The SDK is exclusive to Flutter (not native Android/iOS) and available on pub.dev, where developers are welcome to contribute and provide feedback.

​

Prerequisites

Before you start, ensure the following setup is complete:

• Create an Atoa account: Sign up using our Business App or Web Dashboard.

• Generate API keys: Go to API Access inside the Atoa Business App and generate keys for Sandbox (testing) and Production (live).

• Backend readiness: You must be able to create a Payment Request on your backend server using Atoa APIs before calling the Flutter SDK.

See the Getting Started guide for more information.

​

1: Install the SDK

Run the following to add the Atoa SDK to your Flutter project

flutter pub add atoa_sdk

For usage, sample code to integrate can be found in Example app.

​

2. Import the Package

import 'package:atoa_sdk/atoa_sdk.dart';

​

3: Generate a Payment Request (Backend)

You can generate a payment using the payment-process API, which must be called from your server while creating an order. Refer to the getting started guide to know more

https://api.atoa.me/api/payments/process-payment

curl --location --request POST 'https://api.atoa.me/api/payments/process-payment' \
--header 'Authorization: Bearer {access-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "<Your Unique Customer Id>",
    "orderId": "<Order Id>",
    "amount": "<Total Amount >",
    "currency": "GBP",
    "paymentType": "<DOMESTIC>",
    "autoRedirect": "<true or false>",
    "consumerDetails": {
      "phoneCountryCode": "<Country Code>",
      "phoneNumber": "<Phone Number>"
  }
}'

Note: redirectUrl can be used to redirect the user back to your app after the payment is completed. Follow the information given in the handle redirection steps below

​

4. Launch the Payment Dialog

After obtaining a valid paymentRequestId, you can now invoke the Flutter SDK’s Pay method to show the checkout experience:

final transactionDetails = await AtoaSdk.pay(
      context,
      paymentId: 'your-payment-request-id',
      showHowPaymentWorks: false,
      customerDetails:
        // pass customer details for pre-select bank
       const CustomerDetails(
        phoneCountryCode: '44',
        phoneNumber: '8788899999',
        email: 'aaa@gmail.com',
      ),
      env: AtoaEnv.prod,
      // or AtoaEnv.sandbox

      onUserClose: (
          {required String paymentRequestId,
          Map<String, String>? redirectUrlParams,
          String? signature,
          String? signatureHash}) {
        // handle payment when user close the payment verification bottom sheet

         ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            backgroundColor: RegalColors.darkOrange,
            content: Text(
             'User closed the payment for paymentRequestId: $paymentRequestId',
            ),
          ),
        );
      },
      onPaymentStatusChange: (
          {required String status,
          Map<String, String>? redirectUrlParams,
          String? signature,
          String? signatureHash}) {
        // handle payment status
         print('Payment Status Changed to $status');
      },
      onError: (error) {
        // handle Atoa Mobile SDK error
         print('Error in Atoa Mobile SDK ${error.message}');
      },
    );

​

SDK Parameters

  {
    AtoaException error // Error object which contains error message,
  }

  {
    String status, // Current payment status
    String? atoaSignature, // Atoa signature for verification (optional)
    String? atoaSignatureHash, // Atoa signature hash for verification (optional)
    Map<String, String>? redirectUrlParams, // Additional callback parameters (optional)
  }

  {
    String paymentRequestId, // The payment request ID
    String? atoaSignature, // Atoa signature for verification (optional)
    String? atoaSignatureHash, // Atoa signature hash for verification (optional)
    Map<String, String>? redirectUrlParams, // Additional callback parameters (optional)
  }

​

5. Handle Payment Response

You can handle the payment success, failure, pending and other statuses based on payment response

if (transactionDetails != null) {
  if(transactionDetails.isCompleted) {
    // handle success
  } else {
    // handle failure / pending statuses
  }
} else {
// Bottom sheet was dismissed
}

Sample response can be seen here.

​

6. Handle Redirection (Deep link)

While calling payment-process API to generate a payment, you can specify a redirectUrl in your request body. The redirectUrl, which should be passed as body parameters, redirects to your website and then opens your app via deep linking. This enables users to open your application after payment.

Following the completion of the payment by the customer’s bank app, they will be redirected back to their browser. Atoa will transmit the idempotency id, amount and redirect URL with status as query parameters appended to your specified Redirected URL, forming a URL structure like:

www.yourdeeplink.me?idempotency=ATOA783838728372&redirectUrl=https://pay.me&amount=2

Resources For Implementing deep-linking for your app

• Flutter Docs
• Code With Andrea
• Set up App links for Android
• Set up Universal links for iOS

​

Subscribe to webhook (Recommended)

Atoa uses webhooks to notify your application whenever an event happens in your account. Webhooks are particularly useful for events such as changes in payment status, such as completion, failure, or pending.

To get started, you must Register your webhook endpoint so Atoa knows where to deliver events.

After registration, your endpoint will start receiving detailed webhook payloads. These will inform you of payment status updates, such as COMPLETED, PENDING, or FAILED.

​

Store Fields in Server

Store the following in your backend once the transaction is complete.

 "signatureHash": string
 "paymentIdempotencyId": string

​

7. Check Bank App Installation (Android/iOS Requirements)

Our mobile SDK checks if the bank(using for making payments) app is installed or not. For that, you need to add ‘queries’ tag for android and ‘LSApplicationQueriesSchemes’ key for iOS

 <queries>
    <package android:name="com.barclays.android.barclaysmobilebanking" />
    <package android:name="com.starlingbank.android" />
    <package android:name="com.grppl.android.shell.CMBlloydsTSB73" />
    <package android:name="uk.co.hsbc.hsbcukmobilebanking" />
    <package android:name="com.rbs.mobile.android.natwest" />
    <package android:name="co.uk.Nationwide.Mobile" />
    <package android:name="com.grppl.android.shell.halifax" />
    <package android:name="com.rbs.mobile.android.rbs" />
    <package android:name="uk.co.santander.santanderUK" />
    <package android:name="com.revolut.revolut" />
    <package android:name="co.uk.getmondo" />
    <package android:name="com.grppl.android.shell.BOS" />
    <package android:name="ftb.ibank.android" />
    <package android:name="uk.co.tsb.newmobilebank" />
    <package android:name="com.firstdirect.bankingonthego" />
    <package android:name="com.virginmoney.uk.mobile.android" />
    <package android:name="uk.co.ybs.savings.external" />
    <package android:name="com.transferwise.android" />
    <package android:name="com.nearform.ptsb" />
    <package android:name="com.bankofireland.mobilebanking" />
    <package android:name="aib.ibank.android" />
    <package android:name="uk.co.bankofscotland.businessbank" />
    <package android:name="com.chase.intl" />
  </queries>

    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>pulsesecure</string>
      <string>launchbmb</string>
      <string>lloyds-retail</string>
      <string>hsbc-pwnwguti5z</string>
      <string>uk.co.santander.santanderUK</string>
      <string>fb894703657238109</string>
      <string>bos-retail</string>
      <string>halifax-retail</string>
      <string>monzo</string>
      <string>starlingbank</string>
      <string>tsbmobile</string>
      <string>comfirstdirectbankingonthego</string>
      <string>launchFT</string>
      <string>virginmoneyimport</string>
      <string>ybssavings</string>
      <string>transferwise</string>
      <string>tg</string>
      <string>BOIOneAPP</string>
      <string>ie.aib.mobilebanking</string>
      <string>bos-commercial</string>
      <string>chase-international</string>
    </array>

​

8. Verify Payment Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

You can verify the signature by doing this.

​

9: Test in Sandbox

Use the sandbox for testing different flows

final paymentDetails = AtoaSdk.pay(
context,
paymentId: 'your-payment-request-id',
env: AtoaEnv.sandbox,
// other config properties
);

Refer to the Sandbox Guide to simulate different outcomes.

​

10: Brand & Customize (Optional)

Theme Color: Choose your brand’s hex color in the dashboard. The widget will automatically reflect your theme color. Update your theme color here

Design Guidelines: Refer to our official branding guide to correctly showcase “Pay by Bank” in your checkout. View Figma file

Note: You do not need to pass the theme color in the SDK. Simply configure these once from your Dashboard or Atoa Business App

​

🧠 Tips & Best Practices

✅ To enable faster checkout, Atoa uses the customer’s email and mobile number to pre-select the previously used bank within our network. We recommend passing customer details in the Mobile SDK to support one-click checkout for returning users.

✅ Always validate the payment status using webhooks or polling.

✅ Do not display the payment widget before your backend has successfully created a valid paymentRequestId.

✅ Before going LIVE, ensure to use the production access secret generated from your Business App or Web Dashboard.

✅ Tipping is disabled when using the Mobile SDK. If tipping is part of your experience, we recommend implementing it on your end. ​

​

📩 Need Help?

If you encounter any issues or need help debugging, please refer to our public GitHub repository for detailed setup instructions.

We’re here to help — email us at hello@paywithatoa.co.uk or chat with us via the dashboard’s chat support