Adyen

Start at adyen.com and sign up for a test account — Adyen's test environment is free to create and doesn't require a formal business contract (unlike the live environment, which goes through a sales process with volume discussions). Once your test account is active, log in to the Adyen Customer Area (ca-test.adyen.com). You need three pieces of information for the integration: 1. API Key — go to Developers → API credentials → your credential → click 'Generate API key'. This key goes in the X-API-Key header for all server-to-Adyen calls. It's a server secret and must never appear in your Flutter app or FlutterFlow project. 2. Client Key — on the same API credentials screen, find the Client key field. The client key is safe to use in client-side code (it's designed for that purpose) — it's what the Adyen Drop-in SDK uses to initialize the payment UI. You'll pass this from your proxy to your FlutterFlow app. 3. Merchant Account — your merchant account name is displayed in the top-left of the Customer Area (usually your company name in ALLCAPS format, like YOURCOMPANYNB). You'll include it in every /v71/sessions request body. Also note the API version currently documented: at the time of writing, Adyen's Checkout API is at /v71, but Adyen increments this periodically. Verify the current version at docs.adyen.com/api-explorer before hardcoding /v71 in your proxy — using an outdated version path returns 404 even with valid credentials. Store the API Key in your Cloud Function's environment variables as ADYEN_API_KEY, the client key as ADYEN_CLIENT_KEY, and the merchant account as ADYEN_MERCHANT_ACCOUNT. None of these go in FlutterFlow.

As with any payment integration in FlutterFlow, the Adyen API key is a server secret — placing it in a FlutterFlow API Call header embeds it in your compiled Flutter app, where it can be extracted. A leaked Adyen API key gives an attacker full access to create payment sessions under your merchant account, which could lead to fraudulent transactions billed to real customers. Deploy a Firebase Cloud Function (or Supabase Edge Function) that accepts a payout request from your app (amount in minor units, currency, reference, shopperEmail) and calls Adyen's /v71/sessions endpoint. The function returns the session's id, sessionData, and your clientKey to the app — these are safe to pass to the client for rendering the Drop-in UI. The reference field in the Adyen sessions request is critical: it must be unique per transaction and is how you match Adyen's webhook notification back to the order in your database. Use a UUID or your Firestore/Supabase document ID as the reference. When Adyen's webhook fires with a payment result, it includes this reference so you can look up and update the right order record. Note the amount structure: Adyen requires amount as an object with value (integer in minor units) and currency (ISO 4217 3-letter code). $19.99 = { value: 1999, currency: 'USD' }. $100 = { value: 10000, currency: 'USD' }. This is the most common beginner bug — sending 19.99 as a float instead of 1999 as an integer. For the proxy function below, read the ADYEN_API_KEY, ADYEN_MERCHANT_ACCOUNT, and ADYEN_CLIENT_KEY from process.env. The base URL https://checkout-test.adyen.com/v71 is for test — swap it to your live URL via an env var before going live.

1// Firebase Cloud Function: functions/index.js
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4const axios = require('axios');
5const { v4: uuidv4 } = require('uuid');
6
7admin.initializeApp();
8
9const ADYEN_BASE_URL = process.env.ADYEN_BASE_URL || 'https://checkout-test.adyen.com/v71';
10const ADYEN_API_KEY = process.env.ADYEN_API_KEY;
11const ADYEN_MERCHANT_ACCOUNT = process.env.ADYEN_MERCHANT_ACCOUNT;
12const ADYEN_CLIENT_KEY = process.env.ADYEN_CLIENT_KEY;
13
14exports.createAdyenSession = functions.https.onRequest(async (req, res) => {
15  // CORS for FlutterFlow web preview
16  res.set('Access-Control-Allow-Origin', '*');
17  res.set('Access-Control-Allow-Methods', 'POST, OPTIONS');
18  res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
19  if (req.method === 'OPTIONS') return res.status(204).send('');
20  if (req.method !== 'POST') return res.status(405).send('Method Not Allowed');
21
22  const { amountValue, currency, returnUrl, shopperEmail } = req.body;
23  if (!amountValue || !currency || !returnUrl) {
24    return res.status(400).json({ error: 'amountValue (integer minor units), currency, and returnUrl are required' });
25  }
26
27  const reference = uuidv4(); // unique per transaction
28
29  try {
30    const response = await axios.post(
31      `${ADYEN_BASE_URL}/sessions`,
32      {
33        merchantAccount: ADYEN_MERCHANT_ACCOUNT,
34        amount: { value: amountValue, currency },
35        reference,
36        returnUrl,
37        shopperEmail: shopperEmail || undefined,
38      },
39      { headers: { 'X-API-Key': ADYEN_API_KEY, 'Content-Type': 'application/json' } }
40    );
41
42    // Optionally write pending order to Firestore here
43    const db = admin.firestore();
44    await db.collection('orders').doc(reference).set({
45      reference,
46      amountValue,
47      currency,
48      shopperEmail: shopperEmail || null,
49      status: 'PENDING',
50      createdAt: admin.firestore.FieldValue.serverTimestamp(),
51    });
52
53    return res.status(200).json({
54      sessionId: response.data.id,
55      sessionData: response.data.sessionData,
56      reference,
57      clientKey: ADYEN_CLIENT_KEY,
58    });
59  } catch (error) {
60    const status = error.response?.status || 500;
61    return res.status(status).json({ error: error.response?.data || error.message });
62  }
63});

In FlutterFlow, click API Calls in the left navigation panel. Click + Add and select Create API Group. Name it AdyenProxy. Set the Base URL to your deployed Firebase Function's root URL — for example, https://us-central1-your-project.cloudfunctions.net. Leave the headers empty (no API keys here — those are all in the proxy). Inside the AdyenProxy group, click + Add and select Create API Call. Name it CreateSession. Set the Method to POST and the Endpoint Path to /createAdyenSession. Now click the Variables tab. Add the following variables: - amountValue (Integer) — the payment amount in minor currency units (1999 for $19.99) - currency (String) — ISO 4217 code ('USD', 'EUR', 'GBP') - returnUrl (String) — the URL Adyen redirects to after the hosted payment page - shopperEmail (String) — optional; pass an empty string if not collecting email In the Body tab, set the content type to JSON and write the body template: {"amountValue": {{amountValue}}, "currency": "{{currency}}", "returnUrl": "{{returnUrl}}", "shopperEmail": "{{shopperEmail}}"} Note that amountValue must be an integer with no quotes — {{amountValue}} not "{{amountValue}}". This is critical: if currency units arrive as a quoted string, the Adyen API will reject the request with a 400 validation error. Click the Response & Test tab. Paste a sample success response from your proxy (the JSON object with sessionId, sessionData, reference, clientKey). Click Generate JSON Paths. Add paths for: - $.sessionId → the Adyen session ID - $.sessionData → opaque session data for the Drop-in SDK - $.reference → your order reference (for tracking) - $.clientKey → the Adyen client key Fill in sample variable values and click Test. You should see a live 200 response with real Adyen test session data. If you see a 400 error about the amount, check that amountValue is being sent as a number, not a string.

1{
2  "method": "POST",
3  "endpoint": "/createAdyenSession",
4  "body": {
5    "amountValue": {{amountValue}},
6    "currency": "{{currency}}",
7    "returnUrl": "{{returnUrl}}",
8    "shopperEmail": "{{shopperEmail}}"
9  },
10  "response_paths": {
11    "session_id": "$.sessionId",
12    "session_data": "$.sessionData",
13    "reference": "$.reference",
14    "client_key": "$.clientKey"
15  }
16}

Once your FlutterFlow app has a sessionId and sessionData from the proxy, there are two ways to render the payment UI. The simpler approach is a hosted payment page redirect — Adyen provides a URL where you send the user to complete payment in a browser. The more integrated approach is the Adyen Drop-in widget rendered directly in your app via a Custom Widget. APPROACH 1 — Hosted payment page (recommended for most FlutterFlow apps): Adyen's hosted payment page URL follows the format: https://pay.adyen.com/checkout/{version}/{session_id}?sessionData={encoded_session_data}. After your CreateSession API Call completes, add a 'Launch URL' action (or url_launcher Custom Action) that opens this URL. The user completes payment in a browser tab, and Adyen redirects them to your returnUrl with query parameters indicating the result. You can intercept this with a deep link handler Custom Action or simply show a 'waiting for payment confirmation' screen and poll your Firestore collection until the webhook updates the order status. APPROACH 2 — Adyen Drop-in Custom Widget: For a fully in-app payment experience, add the Adyen Flutter SDK as a Custom Widget. In FlutterFlow, click Custom Code in the left nav → + Add → Widget. Name it AdyenDropIn. In the Dependencies field, search for and add adyen_checkout (the official Adyen pub.dev package — verify the current version). In the Widget Dart code, implement a StatefulWidget that initializes AdyenCheckout with the session ID, session data, and client key, and calls the Drop-in UI. This approach requires testing on a physical device (not in FlutterFlow's web Run Mode), and the Drop-in will not render in the FlutterFlow canvas preview. For most teams building their first Adyen integration in FlutterFlow, the hosted payment page is the right starting point — it requires no Custom Widget code, works on web and mobile equally, and is easier to test. You can always migrate to Drop-in later once the payment flow is working end-to-end.

1// Custom Action: open Adyen hosted payment page
2// Add 'url_launcher' in Custom Code dependencies
3import 'package:url_launcher/url_launcher.dart';
4
5Future openAdyenHostedPage(
6  String sessionId,
7  String sessionData,
8) async {
9  // Adyen hosted page URL — use /v71/ or the version matching your API calls
10  final encodedSessionData = Uri.encodeComponent(sessionData);
11  final url = 'https://pay.adyen.com/checkout/v71/$sessionId?sessionData=$encodedSessionData';
12  final uri = Uri.parse(url);
13  if (await canLaunchUrl(uri)) {
14    await launchUrl(uri, mode: LaunchMode.externalApplication);
15  } else {
16    throw Exception('Could not launch Adyen payment page');
17  }
18}

After a payment completes (or fails), Adyen sends an HMAC-signed webhook notification to your backend — this is the authoritative source of payment truth. The app UI should update based on this webhook, not on the session creation response. In the Adyen Customer Area, go to Developers → Webhooks → + Standard webhook. Set the URL to your Firebase/Supabase webhook function URL (you'll create this now). Set the HMAC key — Adyen generates one for you. Store this HMAC key in your Cloud Function's environment as ADYEN_HMAC_KEY. Deploy a second Cloud Function (adyenWebhook) that: (1) reads the incoming notification body, (2) verifies the HMAC signature using Adyen's HMAC validation algorithm, (3) extracts the merchantReference (your order reference) and the success/failure status, (4) updates the matching Firestore document's status field, and (5) returns a 200 '[accepted]' response to Adyen — Adyen retries webhooks if it doesn't receive this acknowledgment within 10 seconds. In FlutterFlow, bind a list widget or a status text widget to a Firestore Collection or Supabase real-time subscription for the order document keyed by the reference you stored in Step 2. As soon as the webhook fires and updates Firestore, the FlutterFlow widget re-renders with the updated status — no polling required. A unique and consistent reference per transaction (the UUID you generated in the proxy) is what makes this match work. If you reuse references or generate them differently on each retry, the webhook update won't find the right Firestore document. If you'd rather skip setting up the webhook infrastructure and just want payment sessions running in FlutterFlow quickly, RapidDev builds these integrations end-to-end — free scoping call at rapidevelopers.com/contact.

1// Firebase Cloud Function: adyenWebhook
2const crypto = require('crypto');
3
4exports.adyenWebhook = functions.https.onRequest(async (req, res) => {
5  if (req.method !== 'POST') return res.status(405).send('Method Not Allowed');
6
7  const db = admin.firestore();
8  const HMAC_KEY = process.env.ADYEN_HMAC_KEY;
9
10  try {
11    const notificationItems = req.body.notificationItems || [];
12    for (const item of notificationItems) {
13      const notification = item.NotificationRequestItem;
14      const { pspReference, merchantReference, success, eventCode, additionalData } = notification;
15
16      // Verify HMAC signature
17      const hmacSignature = additionalData?.hmacSignature;
18      if (!hmacSignature) continue;
19
20      // Simple HMAC check (use Adyen's SDK or reference implementation for production)
21      const dataToSign = [
22        notification.pspReference,
23        notification.originalReference || '',
24        notification.merchantAccountCode,
25        notification.merchantReference,
26        notification.amount.value,
27        notification.amount.currency,
28        notification.eventCode,
29        notification.success
30      ].join(':');
31
32      const expectedHmac = crypto
33        .createHmac('sha256', Buffer.from(HMAC_KEY, 'hex'))
34        .update(dataToSign)
35        .digest('base64');
36
37      if (expectedHmac !== hmacSignature) {
38        console.warn('HMAC mismatch — possible tampered webhook');
39        continue;
40      }
41
42      // Update Firestore order
43      await db.collection('orders').doc(merchantReference).update({
44        status: success === 'true' ? 'PAID' : 'FAILED',
45        pspReference,
46        eventCode,
47        updatedAt: admin.firestore.FieldValue.serverTimestamp(),
48      });
49    }
50    return res.status(200).send('[accepted]');
51  } catch (error) {
52    console.error('Webhook error:', error);
53    return res.status(500).send('Error');
54  }
55});

Adyen's live environment has a different URL pattern from the test environment — this is one of the most confusing things about Adyen for developers accustomed to a simple sandbox/production base-URL swap. Test endpoint: https://checkout-test.adyen.com/v71 Live endpoint: https://{prefix}-checkout-live.adyenpayments.com/checkout/v71 The {prefix} is specific to your merchant account and is only assigned once Adyen approves your live account. You'll find it in the Adyen Customer Area under Account → Company Account → checkout endpoint. There is no generic 'checkout-live.adyen.com' — you must use your merchant-specific hostname. To switch: set the ADYEN_BASE_URL environment variable in your Cloud Function to your live endpoint hostname. Also update ADYEN_API_KEY to your live API key (generated in the live Customer Area — test keys don't work on live endpoints). Update ADYEN_CLIENT_KEY to the live client key. Redeploy the function. In FlutterFlow, no changes are needed if you've built the API Group pointing to your Cloud Function URL — the function is the single point of environment switching. This is exactly why centralizing all Adyen calls in the proxy is valuable: a single env var change flips the entire integration to live. Before flipping to live, confirm: (1) your Adyen live account is fully onboarded and KYC-completed; (2) your webhook endpoint is configured in the live Customer Area (not just the test one); (3) your HMAC key is updated for the live webhook; and (4) you've done a real low-value test transaction through the live environment with a real card before opening to users.