Worldpay

Contact your Worldpay account manager and ask them to confirm: 1. Which API platform your merchant account uses — legacy UK platform (api.worldpay.com) or the Worldpay from FIS platform (access.worldpay.com) 2. Your test Service Key — for the legacy UK platform this starts with `T_S_` (e.g., `T_S_0123456789abcdef0123456789`) 3. Your live Service Key — starts with `L_S_` 4. Any restrictions on which API endpoints your account has access to (Reporting API and Disputes API are enterprise add-ons not included in standard accounts) If your Service Key starts with `T_S_` or `L_S_`, you are confirmed on the legacy UK platform. If your credentials look different, this tutorial may not fully apply — ask your account manager for the correct API documentation for your platform version. Store your test and live Service Keys separately. Do not use the live key during development — even a single accidental test transaction on a live account may result in real charges. Note that unlike Stripe or Braintree, there is no self-serve Worldpay sandbox you can sign up for. You must wait for your account manager to provision test credentials before you can build anything in Bubble.

1{
2  "legacy_uk_platform": {
3    "test_base_url": "https://api.worldpay.com/v1",
4    "live_base_url": "https://api.worldpay.com/v1",
5    "test_service_key": "T_S_your_test_key_here",
6    "live_service_key": "L_S_your_live_key_here",
7    "auth_pattern": "HTTP Basic Auth — service key as username, empty password"
8  },
9  "fis_platform": {
10    "base_url": "https://access.worldpay.com",
11    "note": "Different credentials and endpoint structure — confirm with your account manager"
12  }
13}

Open your Bubble app. Go to Plugins tab → Add plugins → search 'API Connector' (by Bubble) → Install. Click 'API Connector' in the plugin list. Click 'Add another API'. Name it 'Worldpay Test'. In the base URL field, enter `https://api.worldpay.com/v1`. In the Authentication section, select 'Basic auth'. In the Username field, enter your T_S_* test Service Key. Check the 'Private' checkbox. Leave the Password field completely blank. If Bubble requires a non-empty password value (some versions do), enter a single space — do not enter 'none', 'null', or any placeholder text, as these will be sent as the actual password and cause authentication failures. Add one shared header: `Content-Type: application/json`. Worldpay also supports a `client-key` in the response for hosted payment pages — this is a client-facing value that does not need to be Private, but you will not need it for server-side API calls. Name your API Connector group 'Worldpay Test' (not just 'Worldpay') so that when you create a parallel 'Worldpay Live' group later, the naming prevents accidental cross-environment calls.

1{
2  "api_name": "Worldpay Test",
3  "base_url": "https://api.worldpay.com/v1",
4  "authentication": {
5    "type": "basic_auth",
6    "username": "<private: T_S_your_test_service_key>",
7    "password": ""
8  },
9  "shared_headers": {
10    "Content-Type": "application/json"
11  }
12}

Start with a GET call for order status lookup — this is a safe read-only operation for initialization. Inside the 'Worldpay Test' API group, click 'Add a call'. Name it 'Get Order'. Set the method to GET and the path to `/orders/<orderCode>`. In Bubble's API Connector, the `<orderCode>` part is a dynamic path parameter — enter it as a parameter name that Bubble will substitute at runtime. You need a known test order code to initialize. If you do not have one, you will need to create a test order first (see Step 4) and use that order code here. You can also ask your Worldpay account manager for a sample test order code to use during initialization. Click 'Initialize call' with a real test order code. The successful response includes fields like `orderCode`, `token`, `amount`, `currencyCode`, `paymentStatus` ('SUCCESS', 'FAILED', 'SENT_FOR_REFUND'), `orderDescription`, and payment method details. WORNING: Worldpay order codes are CASE-SENSITIVE. The initialization will fail if the order code you provide does not match exactly — including letter case — the one stored in Worldpay. Never apply Bubble text transformations like `:lowercase()` or `:trim()` to order codes. Use the value exactly as it was submitted. Set 'Use as' to 'Data'.

1{
2  "method": "GET",
3  "path": "/orders/<dynamic: orderCode>",
4  "example_response": {
5    "orderCode": "BUBBLE-ORDER-20260115",
6    "token": "TEST_TOKEN_ABC123",
7    "amount": 1999,
8    "currencyCode": "GBP",
9    "paymentStatus": "SUCCESS",
10    "orderDescription": "Pro plan subscription",
11    "paymentResponse": {
12      "type": "ObfuscatedCard",
13      "name": "Worldpay",
14      "cardType": "VISA_CREDIT",
15      "maskedCardNumber": "**** **** **** 1234"
16    }
17  }
18}

Add a second call to 'Worldpay Test'. Name it 'Create Order'. Method: POST. Path: `/orders`. In the body section, select JSON and enter the order structure: ```json { "token": "<dynamic: payment_token>", "amount": 1999, "currencyCode": "GBP", "name": "<dynamic: customer_name>", "orderDescription": "<dynamic: order_description>", "orderCode": "<dynamic: order_code>", "billingAddress": { "address1": "<dynamic: address1>", "postalCode": "<dynamic: postal_code>", "city": "<dynamic: city>", "countryCode": "GB" } } ``` For the `amount` field: Worldpay uses minor currency units. £19.99 = 1999 pence. In Bubble's formula editor: `round down(Current product's price * 100)`. The amount must be an integer — never a decimal. For `orderCode`: generate a unique code per order. Use your Bubble database record's unique ID with a prefix: `"WP-" + Current Order's unique id`. Store this exact value in your Bubble Order database record — you will need it for lookups and refunds. NEVER apply `:lowercase()`, `:trim()`, or any other text transformation to the order code at any point in your workflows. For `token`: this is the payment token from Worldpay's hosted payment form (a client-side JS component that tokenizes the card). On a Worldpay hosted page integration, the token comes back as a URL parameter when the user returns from Worldpay's checkout. Store it briefly in a page custom state to use in this create order call. Initialize with test values (a test payment token from Worldpay sandbox, a fixed amount). Set 'Use as' to 'Action'.

1{
2  "token": "<dynamic: worldpay_payment_token>",
3  "amount": "<dynamic: amount_in_pence>",
4  "currencyCode": "GBP",
5  "name": "<dynamic: customer_full_name>",
6  "orderDescription": "<dynamic: order_description>",
7  "orderCode": "<dynamic: unique_order_code>",
8  "billingAddress": {
9    "address1": "<dynamic: address_line_1>",
10    "postalCode": "<dynamic: postal_code>",
11    "city": "<dynamic: city>",
12    "countryCode": "GB"
13  },
14  "successUrl": "<dynamic: success_redirect_url>",
15  "failureUrl": "<dynamic: failure_redirect_url>",
16  "pendingUrl": "<dynamic: pending_redirect_url>"
17}

Add a third call to 'Worldpay Test'. Name it 'Refund Order'. Method: POST. Path: `/orders/<dynamic: orderCode>/refund`. In the body section, enter: ```json { "amount": 1999 } ``` Make `amount` a dynamic parameter. On the Bubble page, add a Refund button to each row in your Orders Repeating Group. Set an 'Only when' condition: `Current cell's Order status is 'SUCCESS'` (only settled, successful orders can be refunded). Add a confirmation popup before the refund action: display the order code and amount in GBP (divide Bubble's stored pence amount by 100 for display: `Current cell's Order's amount / 100`). Ask 'Confirm refund of £X.XX?'. The Confirm button triggers: 1. A step calling 'Refund Order' with `orderCode = Current cell's Order's order_code` (passed exactly, no transformations) and `amount = Current cell's Order's amount` (the stored pence value, or a partial refund amount from an input field). 2. A step changing the Bubble Order record's status to 'REFUNDED'. 3. Optionally, a step sending a confirmation email to the customer. Worldpay supports partial refunds (pass an amount less than the original). Store refund amounts in the Bubble database if you allow multiple partial refunds — you need to track how much has already been refunded to prevent over-refunding.

1{
2  "path": "/orders/<dynamic: orderCode>/refund",
3  "method": "POST",
4  "body": {
5    "amount": "<dynamic: refund_amount_in_pence>"
6  }
7}
8
9// Bubble formula for displaying GBP amount from stored pence:
10// Current cell's Order's amount / 100
11// Example: 1999 pence → £19.99
12
13// Bubble formula for partial refund amount conversion:
14// round down(Input Refund Amount's value * 100)
15// Example: user enters 10.00 → 1000 pence

Worldpay can send HTTP notification POSTs to your server when payment status changes. For the legacy UK platform, these are JSON payloads — simpler than Adyen's HMAC-verified format or Authorize.Net's form-encoded Silent Post. To set up the Backend Workflow endpoint (requires paid Bubble plan — Starter or above): 1. Go to Settings → API → check 'This app exposes a Workflow API' → Save. 2. In Backend Workflows, create a new workflow named `worldpay_notification`. 3. Check 'Detect request data'. Leave it waiting. 4. In your Worldpay account settings (through your account manager), register your notification URL: `https://yourapp.bubbleapps.io/api/1.1/wf/worldpay_notification`. 5. Trigger a test payment. Worldpay sends a JSON POST with fields including `orderCode`, `paymentStatus`, `amount`, and `currencyCode`. 6. After detection, add workflow steps: find the Bubble Order where `order_code = notification's orderCode`, update its status based on `paymentStatus` ('SUCCESS' → 'paid', 'FAILED' → 'payment_failed'). To go live: 1. In the API Connector, create a new group 'Worldpay Live' with the same `api.worldpay.com/v1` base URL. Change the Basic Auth username to your L_S_* live Service Key (marked Private). Keep the password blank. 2. Point your Bubble workflows to 'Worldpay Live' calls for production. 3. Update the notification URL in your Worldpay account to your production Bubble app URL if different. RapidDev's team has helped UK-based Bubble founders migrate Worldpay-powered payment flows — if you need help mapping Worldpay's notification fields to your Bubble database schema, reach out at rapidevelopers.com/contact.

1// Worldpay payment notification JSON payload (legacy UK platform)
2{
3  "orderCode": "WP-ORDER-20260115-abc123",
4  "token": "TEST_TOKEN_ABC123",
5  "amount": 1999,
6  "currencyCode": "GBP",
7  "paymentStatus": "SUCCESS",
8  "paymentResponse": {
9    "type": "ObfuscatedCard",
10    "cardType": "VISA_CREDIT",
11    "maskedCardNumber": "**** **** **** 1234"
12  },
13  "environment": "TEST"
14}
15
16// Backend Workflow endpoint:
17// https://yourapp.bubbleapps.io/api/1.1/wf/worldpay_notification
18// (Drop '/initialize' suffix — that is only for Bubble's detection step)