Sage Pay

Log into My Sage Pay portal (MySagePay.sagepay.com or myopayo.opayo.co.uk — both take you to the same portal). Navigate to Settings → Integration. You will find two values: - **Integration Key** (also called Vendor Name in some legacy Sage Pay contexts): a string like `hJYxsw7HLbj40cB8udES8CDRFLhuUskc` - **Integration Password**: a separate secret string You need both to construct the Authorization header. Now, pre-compute the Base64 string. Open your browser's developer console (F12 in Chrome, Cmd+Option+J on Mac). Type: ```javascript btoa('YOUR_INTEGRATION_KEY:YOUR_INTEGRATION_PASSWORD') ``` Press Enter. The console returns a Base64 string like `aEpZeHN3N0hMYmo0MGNCO...`. Copy this entire string — this is the value you will paste into Bubble's Authorization header. Do this twice: 1. Once for the sandbox Integration Key and Password → label the result 'Sandbox Base64' 2. Once for the live Integration Key and Password → label the result 'Live Base64' Store both in a secure location (a password manager or your team's secrets vault). You will need to recompute these strings if you ever rotate your Integration Password.

1// Run this in your browser console (F12 → Console tab)
2// Replace with your actual Integration Key and Password
3
4// Sandbox:
5btoa('YOUR_SANDBOX_INTEGRATION_KEY:YOUR_SANDBOX_INTEGRATION_PASSWORD')
6// Returns: 'WU9VUl9TQU5EQk9YX0lOVEVHUkFUSU9OX0tFWTpZT1VSX1NBTkRCT1hfUEFTU1dPUkQ='
7
8// Live:
9btoa('YOUR_LIVE_INTEGRATION_KEY:YOUR_LIVE_INTEGRATION_PASSWORD')
10// Returns: 'WU9VUl9MSVZFX0lOVEVHUkFUSU9OX0tFWTpZT1VSX0xJVkVfUEFTU1dPUkQ='
11
12// The Authorization header value to use in Bubble:
13// Authorization: Basic WU9VUl9TQU5EQk9YX0lOVEVHUkFUSU9OX0tFWTpZT1VSX1NBTkRCT1hfUEFTU1dPUkQ=

In Bubble, 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 'Opayo Sandbox'. Set the base URL to `https://pi-test.sagepay.com/api/v1`. Do NOT use Bubble's built-in 'Basic auth' authentication option — it would expect username and password fields that Bubble tries to Base64-encode at runtime, but Bubble's API Connector does not reliably do this for custom gateway auth patterns. Instead, use the manual header approach: In the Shared Headers section, click 'Add shared header': - Key: `Authorization` - Value: `Basic YOUR_SANDBOX_BASE64_STRING` (replace with your actual pre-computed sandbox Base64 string from Step 1) - Check the **'Private' checkbox** — this ensures the header value (which contains your credentials) is never sent to the browser Add two more shared headers: - `Content-Type: application/json` - `Cache-Control: no-cache` Name this API group 'Opayo Sandbox' (not just 'Opayo') so when you add the live group later, naming prevents accidental cross-environment calls.

1{
2  "api_name": "Opayo Sandbox",
3  "base_url": "https://pi-test.sagepay.com/api/v1",
4  "shared_headers": {
5    "Authorization": "<private: 'Basic ' + YOUR_SANDBOX_BASE64_STRING>",
6    "Content-Type": "application/json",
7    "Cache-Control": "no-cache"
8  }
9}
10
11// Example Authorization header value:
12// Basic aEpZeHN3N0hMYmo0MGNCO... (your pre-computed sandbox Base64)
13
14// Live configuration (separate API group):
15{
16  "api_name": "Opayo Live",
17  "base_url": "https://pi.sagepay.com/api/v1",
18  "shared_headers": {
19    "Authorization": "<private: 'Basic ' + YOUR_LIVE_BASE64_STRING>",
20    "Content-Type": "application/json"
21  }
22}

Inside the 'Opayo Sandbox' API group, click 'Add a call'. Name it 'Get Transaction'. Set the method to GET and the path to `/transactions/<dynamic: transactionId>`. To initialize, you need a real Opayo transaction ID from a previous test payment. If you do not have one yet, you can: 1. Create a test payment first (Step 4) and come back to initialize this call with the returned ID 2. Ask your Opayo integration contact for a sample sandbox transaction ID With a valid sandbox transaction ID, click 'Initialize call'. The successful response includes: `transactionId`, `transactionType`, `status` ('Ok', 'NotAuthed', 'Rejected', 'Error'), `statusCode`, `statusDetail`, `retrievalReference`, `paymentMethod` (with masked card details), `amount` (in pence), `currency`. Set 'Use as' to 'Data'. Remember: Opayo's PI API does NOT have a 'list all transactions' endpoint. You cannot call an endpoint to retrieve all transactions for a date range. The only way to display a transaction history in Bubble is to store transaction IDs in your Bubble database as they are created, then look them up one by one (or display the locally-stored data without fetching from Opayo on every page load).

1{
2  "method": "GET",
3  "path": "/transactions/<dynamic: transactionId>",
4  "example_response": {
5    "transactionId": "T1234567890ABCDEF1234567890",
6    "transactionType": "Payment",
7    "status": "Ok",
8    "statusCode": "0000",
9    "statusDetail": "The Authorisation was Successful.",
10    "retrievalReference": 19876543,
11    "paymentMethod": {
12      "card": {
13        "cardType": "Visa",
14        "lastFourDigits": "0006",
15        "expiryDate": "0322",
16        "cardIdentifier": "ABC123-MASKED"
17      }
18    },
19    "amount": {
20      "totalAmount": 1999,
21      "saleTxAmount": 1999,
22      "surchargeAmount": 0
23    },
24    "currency": "GBP",
25    "bankAuthorisationCode": "999777"
26  }
27}

Add a second call to 'Opayo Sandbox'. Name it 'Create Payment'. Method: POST. Path: `/transactions`. In the body section, enter the payment structure: ```json { "transactionType": "Payment", "paymentMethod": { "card": { "merchantSessionKey": "<dynamic: merchant_session_key>", "cardIdentifier": "<dynamic: card_identifier>" } }, "vendorTxCode": "<dynamic: vendor_tx_code>", "amount": 1999, "currency": "GBP", "description": "<dynamic: order_description>", "apply3DSecure": "UseMSPSetting", "customerFirstName": "<dynamic: first_name>", "customerLastName": "<dynamic: last_name>", "billingAddress": { "address1": "<dynamic: address1>", "postalCode": "<dynamic: postal_code>", "city": "<dynamic: city>", "country": "GB" } } ``` The `vendorTxCode` is the most critical field. It MUST be unique for every transaction — Opayo returns error `5009` ('Duplicate vendorTxCode') if you reuse any previous code. Generate it in your Bubble workflow using: `"BUBBLE-" + Current date/time's Unix timestamp`. This ensures uniqueness as long as no two transactions trigger simultaneously. The `amount` must be in pence (minor currency units): £19.99 = 1999. In Bubble's formula editor: `round down(Product's price * 100)`. Note: the `cardIdentifier` and `merchantSessionKey` come from Opayo's Sagepay JS (the client-side card tokenization library). You embed this JS in a Bubble HTML element to capture card details securely. The JS library tokenizes the card and returns a `cardIdentifier` and `merchantSessionKey` that your Bubble workflow collects (via Toolbox plugin's bubble_fn_ pattern) and passes to this API call. Set 'Use as' to 'Action'. After a successful Create Payment call, capture the returned `transactionId` and store it in your Bubble database immediately.

1{
2  "transactionType": "Payment",
3  "paymentMethod": {
4    "card": {
5      "merchantSessionKey": "<dynamic: merchant_session_key>",
6      "cardIdentifier": "<dynamic: card_identifier>"
7    }
8  },
9  "vendorTxCode": "<dynamic: vendor_tx_code>",
10  "amount": "<dynamic: amount_in_pence>",
11  "currency": "GBP",
12  "description": "<dynamic: order_description>",
13  "apply3DSecure": "UseMSPSetting",
14  "customerFirstName": "<dynamic: first_name>",
15  "customerLastName": "<dynamic: last_name>",
16  "billingAddress": {
17    "address1": "<dynamic: billing_address1>",
18    "postalCode": "<dynamic: billing_postal_code>",
19    "city": "<dynamic: billing_city>",
20    "country": "GB"
21  }
22}
23
24// vendorTxCode generation in Bubble formula editor:
25// "BUBBLE-" + Current date/time's Unix timestamp
26// Example result: "BUBBLE-1737043200"
27
28// Amount conversion in Bubble formula editor:
29// round down(Current product's price * 100)
30// Example: £19.99 → 1999

Add a third call to 'Opayo Sandbox'. Name it 'Create Refund'. Method: POST. Path: `/transactions` (same endpoint as payment creation — the `transactionType` field distinguishes the operation). In the body section: ```json { "transactionType": "Refund", "vendorTxCode": "<dynamic: refund_vendor_tx_code>", "amount": 1999, "currency": "GBP", "description": "Refund for order", "referenceTransactionId": "<dynamic: parent_transaction_id>" } ``` Key points: - `transactionType` is `"Refund"` (not `"Payment"`) — this field switches the operation - `vendorTxCode` must be a NEW unique code, not the original payment's vendorTxCode. Use: `"REFUND-" + Current date/time's Unix timestamp` - `referenceTransactionId` is the original payment's `transactionId` stored in your Bubble database - `amount` is in pence — same conversion as payment: `round down(Refund amount * 100)` In your Bubble page, add a Refund button to the Orders Repeating Group with two 'Only when' conditions: 1. `Current cell's Order's status is 'Ok'` — Opayo only refunds transactions with Ok status that have settled (typically 24–48 hours after authorization) 2. `Current date/time > Current cell's Order's created_at + 24 hours` — optional but recommended to prevent refund attempts on unsettled transactions Opayo returns error `3073` if you attempt a refund on a transaction that has not yet settled. Add workflow logic to display a friendly message when 3073 is encountered: 'This payment is still processing — refunds are available after settlement (typically 24–48 hours).' RapidDev's team has configured Opayo refund flows for dozens of UK-based Bubble apps. If you need help mapping Opayo's settlement timeline to your Bubble order management system, schedule a free scoping call at rapidevelopers.com/contact.

1{
2  "transactionType": "Refund",
3  "vendorTxCode": "<dynamic: refund_vendor_tx_code>",
4  "amount": "<dynamic: refund_amount_in_pence>",
5  "currency": "GBP",
6  "description": "Refund for order",
7  "referenceTransactionId": "<dynamic: parent_transaction_id_from_bubble_db>"
8}
9
10// Refund vendorTxCode generation in Bubble formula editor:
11// "REFUND-" + Current date/time's Unix timestamp
12// Example: "REFUND-1737043800"
13
14// Opayo error 3073: Transaction not yet settled
15// Add 'Only when' condition: Current cell's Order's created_at < Current date/time - 1 day

Opayo can POST payment status notifications to your server when transaction status changes. Unlike Adyen, Opayo's notifications do not require HMAC verification — they are straightforward JSON POSTs (on the PI API, at least). 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 `opayo_notification`. 3. Check 'Detect request data'. Leave it waiting. 4. Contact your Opayo integration support or configure the notification URL in My Sage Pay portal → Settings → Notifications. Register: `https://yourapp.bubbleapps.io/api/1.1/wf/opayo_notification`. 5. Process a test payment. Opayo sends a POST with transaction status details. 6. After detection, add workflow steps: find the Order where `transaction_id = incoming notification's transactionId`, update status based on the notification's status field. To go live: 1. Pre-compute the live Base64 string from your live Integration Key and Integration Password. 2. In the API Connector, click 'Add another API' and name it 'Opayo Live'. Set the base URL to `https://pi.sagepay.com/api/v1`. Add the Authorization Private header with the live Base64 string. 3. Switch your Bubble workflows to use the 'Opayo Live' API calls. 4. Update the notification URL in My Sage Pay to your production Bubble app URL. Before your first live transaction, run a £1.00 test with a real card and verify the full flow: payment creation → Bubble database record → notification receipt → status update.

1// Opayo PI API notification payload (example)
2{
3  "transactionId": "T1234567890ABCDEF1234567890",
4  "transactionType": "Payment",
5  "status": "Ok",
6  "statusCode": "0000",
7  "statusDetail": "The Authorisation was Successful.",
8  "vendorTxCode": "BUBBLE-1737043200",
9  "retrievalReference": 19876543,
10  "amount": {
11    "totalAmount": 1999
12  },
13  "currency": "GBP"
14}
15
16// Sandbox base URL: https://pi-test.sagepay.com/api/v1
17// Live base URL:    https://pi.sagepay.com/api/v1
18
19// Backend Workflow URL:
20// https://yourapp.bubbleapps.io/api/1.1/wf/opayo_notification
21// (NOT ending in '/initialize' — that suffix is only for Bubble's detection step)