2Checkout (now Verifone)

Log in to the 2Checkout Control Panel at app.2checkout.com. Navigate to Account → Integrations → API. You need two values: your Merchant Code (a short uppercase alphanumeric identifier like 'ABCDE123') and your Secret Word (a long random string — this is your HMAC signing key, sometimes called Secret Key or Secret Word in the UI). Copy both and store them securely. Critically, understand what you're working with before writing a single Bubble configuration: the 2Checkout Authorization header is not a simple Bearer token. It looks like this: `Authorization: code="MERCHANT_CODE" date="1700000000" hash="abc123def..."` The `hash` value is HMAC-SHA256 of the string `MERCHANT_CODE1700000000` (merchant code concatenated directly with the Unix timestamp in seconds), signed with your Secret Word. The timestamp must be within a few minutes of 2Checkout's server clock. This means the entire Authorization header string is different on every request — you cannot save it once in Bubble's API Connector. Also confirm which API version you're using. This guide covers v6.0 (base URL `https://api.2checkout.com/rest/6.0`). If you have an older account that previously used v4.0, endpoint paths and response field names differ — check your 2Checkout Control Panel or contact their support to confirm your account's API version. Finally, identify which pricing tier your account is on: 2SELL (one-time payments), 2SUBSCRIBE (subscriptions), or 2MONETIZE (full tax compliance). Your tier determines which API endpoints are available — the subscriptions and tax endpoints are tier-gated.

The per-request HMAC computation requires running JavaScript inside a Bubble workflow. The Toolbox plugin by Zeroqode provides the 'Run Javascript' action that makes this possible. Install it first. Go to your Bubble app → Plugins tab → click Add plugins → search for 'Toolbox' → find the result by Zeroqode → click Install. The plugin is free. Next, on the page where you will display 2Checkout data (for example, your Orders page), create a custom state to hold the computed Authorization header string: 1. Click on the page background in the Bubble editor (not on any element) 2. In the right panel, click 'Add a custom state' 3. Name it `auth_header`, type: Text, default value: empty Also create a second custom state: - Name: `unix_timestamp`, type: Number, default value: 0 These states act as a secure relay: the JavaScript action computes the header and writes it to `auth_header`, then the API Connector call reads from `auth_header`. Your Secret Word never appears in the Authorization header stored in Bubble's configuration — only the computed HMAC output does. Note on security: The Secret Word will be passed into the JavaScript action as a workflow input from a Private API Connector field. This means it travels server-side in the API Connector context, not as a visible client-side JavaScript variable hardcoded in the page. This is the correct pattern for Bubble.

Now set up the API Connector. Go to Plugins tab → click API Connector (by Bubble) — if it's not installed, click Add plugins, search 'API Connector', and install it. Inside the API Connector, click 'Add another API'. Name it `2Checkout`. In the Shared headers section, add: - Header key: `Content-Type`, value: `application/json` (leave the Private checkbox unchecked — Content-Type is not sensitive) Do NOT add an Authorization header here as a static shared header — because the auth value changes per request, you will pass it as a call-level header on each individual API call, populated dynamically from the `auth_header` custom state. Now add your first API call. Click 'Add another call'. Name it `Get Orders`. Set: - Use as: Data - Method: GET - URL: `https://api.2checkout.com/rest/6.0/orders/` At the call level (not the shared level), add a header: - Key: `Authorization` - Value: `<auth_header_state>` (you will make this dynamic in workflows — for now, type a placeholder) - Check the **Private** checkbox on this Authorization header Add URL parameters: - `Limit`: `20` (initialize value, mark as 'Private' unchecked — this is a query parameter, not a secret) - `Page`: `1` Before you can initialize the call, you need a valid Authorization header. Use the Toolbox plugin JavaScript action manually once to compute one for initialization: In any test workflow, add a 'Run Javascript' action. Paste this code to compute a test auth header (replace YOUR_MERCHANT_CODE and YOUR_SECRET_WORD with your actual values temporarily for the initialization test only — remove them immediately after): ```javascript var merchantCode = "YOUR_MERCHANT_CODE"; var secretWord = "YOUR_SECRET_WORD"; var timestamp = Math.floor(Date.now() / 1000).toString(); var message = merchantCode + timestamp; var hash = CryptoJS.HmacSHA256(message, secretWord).toString(); var authHeader = 'code="' + merchantCode + '" date="' + timestamp + '" hash="' + hash + '"'; bubble_fn_result(authHeader); ``` Run this action, copy the output, paste it as the Authorization header value in the API Connector for the Initialize Call step. Click Initialize call — you should get a 200 response with an `Items` array and `TotalCount` integer. Bubble auto-detects the response fields. After successful initialization, clear the hardcoded credentials from the JavaScript action — they were only needed for this one-time initialization step.

1{
2  "method": "GET",
3  "url": "https://api.2checkout.com/rest/6.0/orders/",
4  "headers": {
5    "Content-Type": "application/json",
6    "Authorization": "<auth_header_state> (Private, dynamic from custom state)"
7  },
8  "params": {
9    "Limit": "20",
10    "Page": "1"
11  }
12}

This is the core of the integration. You need a reusable workflow (or a consistent set of steps you repeat before every 2Checkout API call) that computes the HMAC and stores it in the `auth_header` custom state. Set it up once and reuse it across all pages that call 2Checkout. In the Bubble workflow editor on your Orders page, create a new workflow triggered by whatever action loads data (for example, 'When page is loaded' or a Button click). Before the API Connector call step, add these steps: **Step 1 — Run Javascript (Toolbox plugin)** Action: 'Run Javascript' Javascript to run: ```javascript var merchantCode = bubble_fn_merchantCode(); var secretWord = bubble_fn_secretWord(); var timestamp = Math.floor(Date.now() / 1000).toString(); var message = merchantCode + timestamp; var hash = CryptoJS.HmacSHA256(message, secretWord).toString(); var authHeader = 'code="' + merchantCode + '" date="' + timestamp + '" hash="' + hash + '"'; bubble_fn_result(authHeader); ``` In the Toolbox 'Run Javascript' action, you define input parameters. Map: - `bubble_fn_merchantCode` → your Merchant Code (stored as a Private parameter in the API Connector or in Bubble's app settings) - `bubble_fn_secretWord` → your Secret Word (same Private storage) The action's output (`result`) is the full Authorization header string. **Step 2 — Set State** Element: current page Custom state: `auth_header` Value: Result of Step 1 (the JavaScript output) **Step 3 — API Connector call (Get Orders)** In the Authorization header field for this call step, set the value to: `Current page's auth_header` This three-step pattern (Run JS → Set State → API Call) must be repeated before every 2Checkout API call in every workflow. The timestamp in the HMAC is only valid for a few minutes — do not set auth once on page load and reuse it across multiple delayed actions. Recompute immediately before each call. If you use Backend Workflows to process 2Checkout data, note that Backend Workflows run server-side and CryptoJS is not available in that context. The HMAC computation must happen client-side (in a page workflow) before the server-side API call. Backend Workflows are for receiving inbound IPN events, not for making outbound 2Checkout API calls.

1// Toolbox 'Run Javascript' action content
2// Inputs: bubble_fn_merchantCode (Private), bubble_fn_secretWord (Private)
3
4var merchantCode = bubble_fn_merchantCode();
5var secretWord = bubble_fn_secretWord();
6var timestamp = Math.floor(Date.now() / 1000).toString();
7var message = merchantCode + timestamp;
8var hash = CryptoJS.HmacSHA256(message, secretWord).toString();
9var authHeader = 'code="' + merchantCode + '" date="' + timestamp + '" hash="' + hash + '"';
10bubble_fn_result(authHeader);

With the auth computation working, wire up the orders display and refund actions in your Bubble page. **Orders Repeating Group:** 1. Add a Repeating Group element to your page. Set: - Type of content: 2Checkout Get Orders's Items (Bubble's detected response list type) - Data source: Leave empty for now — you will set it via workflow 2. On the Page Load workflow (or a Load Orders button click), run the three-step auth-then-API pattern and then set the Repeating Group's data to the API call result's `Items` list. 3. Inside the Repeating Group cell, add text elements bound to `Current cell's OrderNo`, `Current cell's OrderDate`, `Current cell's Total`, `Current cell's BillingDetails CustomerName`. 4. Add a Load More button below the Repeating Group. Its workflow: - Step 1: Set State — increment a `page_offset` custom state by 1 - Step 2–4: Compute auth, Set State (auth_header), API call with `Page = Current page's page_offset` - Append the new results to the Repeating Group (use Bubble's 'Make changes to' list merge pattern or a separate display list state) **Refund Workflow:** Add a Refund button inside the Repeating Group cell. Set up a confirmation workflow: 1. Button click → Show a Popup with 'Are you sure you want to refund Order #[OrderNo]?' 2. Popup confirm button workflow: - Step 1 (Run Javascript): compute auth header with HMAC - Step 2 (Set State): `auth_header` = Step 1 result - Step 3 (API Call): Add a new API Connector call named 'Refund Order' - Method: POST - URL: `https://api.2checkout.com/rest/6.0/orders/<OrderNo>/refund/` - Authorization header: `Current page's auth_header` (Private) - Body: `{ "comment": "Refund requested via admin dashboard", "amount": <amount_to_refund> }` - Step 4 (Reload): Trigger the Load Orders workflow to refresh the list Add a custom state `selected_order_no` (Text) that you set when the Refund button is clicked (before the popup opens) so the confirmation popup knows which order to refund. Note on refund eligibility: 2Checkout's refund eligibility varies by payment method and jurisdiction — some methods allow refunds for under 24 hours, others up to 180 days. The API returns an error with message 'Order cannot be refunded' if the window has passed. Display a note in your UI: 'Refund availability depends on payment method and 2Checkout policies — contact support if the refund button is unavailable.'

1{
2  "method": "POST",
3  "url": "https://api.2checkout.com/rest/6.0/orders/<OrderNo>/refund/",
4  "headers": {
5    "Content-Type": "application/json",
6    "Authorization": "<auth_header_state> (Private, from custom state)"
7  },
8  "body": {
9    "comment": "Refund requested via admin dashboard",
10    "amount": "<dynamic: order total or partial amount>"
11  }
12}

2Checkout's IPN (Instant Payment Notification) sends a POST request to your Bubble app whenever a payment event occurs — order completed, subscription renewed, chargeback opened, refund processed. This is far more efficient than polling the /orders endpoint because Bubble processes the event in real time with zero Workload Unit polling cost. **Important: Backend Workflows require a paid Bubble plan (Starter or higher). Free plan Bubble apps cannot use this feature.** To set up the IPN Backend Workflow: 1. In Bubble, go to Settings → API → check 'This app exposes a Workflow API' 2. Navigate to Backend Workflows (in the left sidebar under 'Workflows') 3. Click 'Add new endpoint'. Name it `2co_ipn` 4. Click 'Detect request data' — this step waits for a real incoming POST from 2Checkout to auto-detect the field types 5. In your 2Checkout Control Panel, go to Account → Integrations → IPN → IPN Settings 6. Set the IPN URL to: `https://your-app.bubbleapps.io/api/1.1/wf/2co_ipn` 7. In 2Checkout Control Panel, click 'Test IPN' to send a sample POST to your endpoint 8. Back in Bubble, the Detect step should capture the test event and display the detected fields The IPN payload from 2Checkout is sent as `application/x-www-form-urlencoded` (form-encoded), not JSON. The key fields to map are: - `MESSAGE_TYPE`: 'ORDER_CREATED', 'FRAUD_STATUS_CHANGED', 'REFUND_ISSUED', 'SUBSCRIPTION_RENEW', 'CHARGEBACK_INITIATED' - `ORDER_REF`: the 2Checkout order reference number (matches `OrderNo` in the REST API) - `IPN_STATUS`: 'COMPLETE', 'PENDING', 'FRAUD' In the Backend Workflow, add steps: - Find the matching Order Thing in your Bubble database where `OrderRef = Detected data's ORDER_REF` - Make changes to that Thing: set `status = Detected data's IPN_STATUS` - Add conditional branches: if `MESSAGE_TYPE = 'CHARGEBACK_INITIATED'`, send an email to your admin address **Switching to production:** - No base URL change needed — `https://api.2checkout.com` serves both test and live accounts. Test accounts and live accounts are separate accounts with different Merchant Codes and Secret Words. - Update your API Connector's Merchant Code and Secret Word Private fields to your live account values - Update the IPN URL in 2Checkout to use your production Bubble app domain if different - Test a real small transaction end-to-end before going fully live RapidDev's team has configured 2Checkout integrations in Bubble apps with subscription tiers and automated chargeback workflows — if you're building a complex SaaS monetization stack on Bubble, book a free scoping call at rapidevelopers.com/contact.

1// 2Checkout IPN endpoint URL format
2// Production: https://your-app.bubbleapps.io/api/1.1/wf/2co_ipn
3// Custom domain: https://your-domain.com/api/1.1/wf/2co_ipn
4
5// Sample IPN payload fields (form-encoded):
6// MESSAGE_TYPE=ORDER_CREATED
7// ORDER_REF=123456789
8// IPN_STATUS=COMPLETE
9// TOTAL_AMOUNT=29.99
10// CURRENCY=USD
11// CUSTOMER_EMAIL=customer@example.com
12// SUBSCRIPTION_STATUS=active
13// NEXT_RENEWAL_DATE=2027-01-10