Adyen

Before opening Bubble, log into the Adyen Customer Area (ca-test.adyen.com for test, ca-live.adyen.com for live). Navigate to Developers → API credentials. You need three values: the API Key (a long string starting with AQE...), the Merchant Account code (a short identifier assigned to your business), and the Client Key (used for the Drop-in UI if you embed it via an HTML element). Important: also identify your live base URL prefix. In the Customer Area, go to Account → Merchant accounts → your account → and look for the 'Live endpoint URL prefix' field. This prefix forms the subdomain of your live checkout URL. Write it down now — many Bubble builders discover this only when they try to go live and get 401 errors. Store it separately from the test URL. If any of these values are missing or API access is not yet enabled, contact your Adyen account manager before proceeding. Adyen does not offer self-serve API key generation for all regions and account tiers.

1{
2  "test_base_url": "https://checkout-test.adyen.com/v71",
3  "live_base_url": "https://{YOUR_PREFIX}-checkout-live.adyenpayments.com/checkout/v71",
4  "api_key": "AQEy...your_api_key...",
5  "merchant_account": "YourMerchantAccountCODE",
6  "client_key": "live_XXXX...or test_XXXX..."
7}

Open your Bubble app and go to the Plugins tab. Click 'Add plugins', search for 'API Connector' (the official plugin by Bubble), and install it. Then click 'API Connector' in the plugin list to open its settings panel. Click 'Add another API' and name it 'Adyen Checkout'. In the 'Shared headers' section, add a new header: Key = `X-API-Key`, Value = your API Key. Critically, check the 'Private' checkbox next to this header. This ensures the key is injected server-side by Bubble's infrastructure and never sent to the browser. Add a second shared header: Key = `Content-Type`, Value = `application/json`. In the base URL field, enter the Adyen test base URL: `https://checkout-test.adyen.com/v71`. You will switch this to the live URL when going to production. Do not add the API Key as a URL parameter or as an Action-level header — the Private shared header is the correct and secure location.

1{
2  "api_name": "Adyen Checkout",
3  "base_url": "https://checkout-test.adyen.com/v71",
4  "shared_headers": {
5    "X-API-Key": "<private: your_api_key>",
6    "Content-Type": "application/json"
7  }
8}

Inside the 'Adyen Checkout' API group in the API Connector, click 'Add a call'. Name it 'Create Session'. Set the method to POST and the endpoint path to `/sessions` (which appends to your base URL to form the full Checkout API sessions endpoint). In the body section, select JSON and enter the following structure. Mark `merchantAccount` and `amount.value` as dynamic so Bubble can inject them per transaction: ```json { "merchantAccount": "<YourMerchantAccountCODE>", "amount": { "value": 1999, "currency": "EUR" }, "reference": "ORDER-12345", "returnUrl": "https://yourdomain.com/payment-result" } ``` For `amount.value`, enter a real integer like 1999. Remember: Adyen amounts are always integers in the smallest currency unit — €19.99 becomes 1999, £19.99 becomes 1999, ¥1999 stays 1999 (JPY has no minor unit). KWD uses ×1000. Click 'Initialize call'. Bubble will execute the call with your test values and detect the response shape. The successful response includes `id` (the sessionId), `sessionData`, and `amount`. Bubble auto-maps these fields. If initialization fails with 'There was an issue setting up your call', verify the API Key header (Private checkbox) and that your test merchant account is active. After successful initialization, set 'Use as' to 'Action' since this call creates a session (not a data fetch).

1{
2  "method": "POST",
3  "endpoint": "/sessions",
4  "body": {
5    "merchantAccount": "<dynamic: merchant_account>",
6    "amount": {
7      "value": "<dynamic: amount_in_minor_units>",
8      "currency": "<dynamic: currency_code>"
9    },
10    "reference": "<dynamic: order_reference>",
11    "returnUrl": "<dynamic: return_url>",
12    "countryCode": "<dynamic: country_code>"
13  }
14}

On your Bubble checkout page, create the elements needed to trigger and display the Adyen checkout. You will need: a 'Pay Now' button, two custom states on the page (type: text) named `adyen_session_id` and `adyen_session_data`, and an HTML element for the Drop-in or a redirect mechanism. Set up the 'Pay Now' button's workflow: 1. Add a step: 'Plugins → Adyen Checkout - Create Session'. Fill in the dynamic fields: `merchant_account` = your merchant account code (can be a Bubble option set or text constant), `amount_in_minor_units` = Current product's price × 100 (use the formula editor: `round down(Current product's price * 100)`), `currency_code` = 'EUR' (or your currency), `order_reference` = a unique ID (use the order's unique ID from your database), `return_url` = your payment-result page URL. 2. Add a step: 'Set state of' the page's `adyen_session_id` to `Result of step 1's id`. 3. Add a step: 'Set state of' the page's `adyen_session_data` to `Result of step 1's sessionData`. 4. Add a step: 'Go to page' or 'Open an external website' pointing to Adyen's hosted checkout page. The redirect URL format is: `https://checkoutshopper-test.adyen.com/checkoutshopper/securedfields/{sessionId}?sessionData={sessionData}&environment=test`. Replace `{sessionId}` and `{sessionData}` with your custom states using Bubble's dynamic text editor. For production, switch to `checkoutshopper-live.adyen.com` and pass the live `environment=live` parameter. When Adyen completes the payment, it redirects back to your `returnUrl` — use URL parameters on that page to detect the `sessionResult` query parameter and trigger a status-check workflow.

1// Bubble workflow step: amount conversion formula
2// In the formula editor for 'amount_in_minor_units':
3// round down(Current product's price * 100)
4
5// Redirect URL for Adyen hosted checkout (test)
6// Construct in Bubble's dynamic text editor:
7// https://checkoutshopper-test.adyen.com/checkoutshopper/securedfields/
8// + Page's adyen_session_id
9// + ?sessionData=
10// + Page's adyen_session_data
11// + &environment=test

When Adyen processes a payment, it sends an AUTHORISATION notification to a webhook URL you register. This step is only possible on paid Bubble plans (Starter+) — if you are on the Free plan, skip this step and instead poll the Adyen sessions endpoint on your returnUrl page. To set up the Backend Workflow: 1. In your Bubble app, go to Settings → API. Check 'This app exposes a Workflow API' and save. 2. In the Bubble editor, switch to the Backend Workflows view (the icon looks like a server). Click 'New API workflow', name it `adyen_notification`. 3. Check 'Detect request data' and click the 'Detect' button. Leave it running. 4. In Adyen's Customer Area, go to Developers → Webhooks → Standard webhook → Add new endpoint. Enter your Bubble endpoint URL: `https://yourtestapp.bubbleapps.io/api/1.1/wf/adyen_notification`. 5. Send a test webhook from Adyen. Bubble will detect the structure: `notificationItems[0].NotificationRequestItem` contains `pspReference`, `merchantReference`, `amount.value`, `eventCode`, `success`, and `additionalData.hmacSignature`. 6. After detection, click 'Save' in Bubble's Detect step to lock in the schema. In the workflow steps, add logic to: - Look up the Order in Bubble DB where `reference = notificationItems first item's merchantReference` - If `eventCode = AUTHORISATION` and `success = true`, change the Order status to 'paid' - Return HTTP 200 immediately (Bubble does this by default) with body `[accepted]` — Adyen requires this exact response within 10 seconds IMPORTANT: Adyen's webhook payload includes an HMAC signature in `additionalData.hmacSignature`. Full HMAC verification using CryptoJS (concatenating the 8 required fields in exact order) is complex in Bubble but is the correct security practice. At minimum, verify the `merchantAccountCode` matches your account before updating order status. RapidDev's team has implemented Adyen webhook flows in dozens of Bubble apps — if the HMAC verification setup is blocking your launch, reach out for a free scoping call at rapidevelopers.com/contact.

1// Adyen AUTHORISATION webhook payload structure (simplified)
2{
3  "live": "false",
4  "notificationItems": [
5    {
6      "NotificationRequestItem": {
7        "additionalData": {
8          "hmacSignature": "HMAC_VALUE_HERE"
9        },
10        "amount": {
11          "currency": "EUR",
12          "value": 1999
13        },
14        "eventCode": "AUTHORISATION",
15        "eventDate": "2026-01-15T12:00:00+00:00",
16        "merchantAccountCode": "YourMerchantAccountCODE",
17        "merchantReference": "ORDER-12345",
18        "paymentMethod": "visa",
19        "pspReference": "ABC123DEF456",
20        "reason": "",
21        "success": "true"
22      }
23    }
24  ]
25}
26
27// HMAC signing string field order (concatenate with colons):
28// pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success
29// Empty fields use empty string, NOT null

When you are ready to accept real payments, you must update three things in Bubble: 1. The API Connector base URL: Open Plugins → API Connector → Adyen Checkout. Change the base URL from `https://checkout-test.adyen.com/v71` to your live URL: `https://{YOUR_PREFIX}-checkout-live.adyenpayments.com/checkout/v71`. Replace `{YOUR_PREFIX}` with the merchant-specific subdomain prefix from your Adyen Customer Area. This is NOT a generic Adyen URL — every merchant gets a unique prefix. 2. The X-API-Key header: Click the Private X-API-Key header row and replace the test API key value with your live API key. The live key is a different credential generated in ca-live.adyen.com. After changing the key, re-initialize the Create Session call with a small live test amount (you can void or refund it immediately). 3. The checkout redirect URL: In your Bubble workflow, update the redirect URL from `checkoutshopper-test.adyen.com` to `checkoutshopper-live.adyen.com` and change the `environment` parameter to `live`. 4. The Backend Workflow webhook URL: Update the registered endpoint in Adyen's Customer Area (live) to point to your production Bubble app URL if different from the test URL. Verify that the live merchant account has your preferred payment methods (Visa, Mastercard, iDEAL, etc.) enabled in the Customer Area → Account → Payment methods. Payment methods must be explicitly enabled — they are not all on by default.

1{
2  "test_config": {
3    "base_url": "https://checkout-test.adyen.com/v71",
4    "api_key": "test_XXXXXXX...",
5    "checkout_redirect": "https://checkoutshopper-test.adyen.com/..."
6  },
7  "live_config": {
8    "base_url": "https://{YOUR_MERCHANT_PREFIX}-checkout-live.adyenpayments.com/checkout/v71",
9    "api_key": "live_XXXXXXX...",
10    "checkout_redirect": "https://checkoutshopper-live.adyen.com/..."
11  }
12}