How to Integrate Retool with Adyen

Adyen uses a single API key for authentication across most of its APIs, but different services use different base URLs. You will need to create separate Retool REST API Resources for each Adyen API family you use. First, obtain your Adyen API key from the Customer Area: navigate to Developers → API credentials → Create new API credential. Set the credential type to 'Web service user'. Under Roles, enable the specific roles your Retool app needs — for example: Merchant Payments role for Checkout API, Merchant Report Download role for the Reporting API, and Merchant Chargeback Management role for the Disputes API. Copy the generated API key. Store the API key as a secret configuration variable in Retool: Settings → Configuration Variables → Add Variable → name it ADYEN_API_KEY, mark as secret. Now create REST API Resources in Retool. Navigate to Resources tab → Add Resource → REST API for each Adyen API: 1. Adyen Checkout API: - Base URL: https://checkout-live.adyenpayments.com/checkout/v71 (production) or https://checkout-test.adyen.com/v71 (test) - Headers: X-API-Key: {{ retoolContext.configVars.ADYEN_API_KEY }}, Content-Type: application/json 2. Adyen Management API: - Base URL: https://management-live.adyenpayments.com/v1 (production) or https://management-test.adyen.com/v1 (test) - Headers: X-API-Key: {{ retoolContext.configVars.ADYEN_API_KEY }}, Content-Type: application/json 3. Adyen Reporting API: - Base URL: https://ca-live.adyen.com/reports/download (for report file access) — note that Adyen's reporting data is accessed via the /transactions endpoint under the Merchant API at https://management-live.adyenpayments.com/v1/merchants/{merchantId}/transactions Click Save for each resource. Create one resource for each Adyen API family you plan to use.

Create your primary data query for payment transaction data. In your Retool app, click + New in the query panel. Select your Adyen Management API resource. Set the method to POST and the path to /merchants/{{ retoolContext.configVars.ADYEN_MERCHANT_ID }}/transactions for the Transactions API (Adyen uses POST for search/filter operations on this endpoint). Set the request body to a JSON object with filters for the transaction search. Adyen's transactions endpoint accepts dateTimeFrom, dateTimeTo, paymentMethod, balanceAccountId, and statuses as filter fields in the request body. Add reference components to your app: - A DateRange picker component — use its values in dateTimeFrom and dateTimeTo (formatted as ISO 8601 strings) - A Select component for payment method filter (visa, mc, ideal, paypal, etc.) - A Text input for PSP reference search Set the query body: { 'dateTimeFrom': '{{ dateRange.start ? new Date(dateRange.start).toISOString() : '' }}', 'dateTimeTo': '{{ dateRange.end ? new Date(dateRange.end).toISOString() : '' }}', 'paymentMethod': '{{ methodSelect.value || null }}', 'cursor': '{{ cursor_state.value || null }}' } Adyen uses cursor-based pagination. The response includes a 'nextCursor' field — store it in a state variable and use it in subsequent requests to load additional pages. Add a JavaScript transformer to reshape the transaction response. Drag a Table component and bind it to the transformed data. Configure columns for PSP reference, merchant reference, amount, currency, status, payment method, and created date.

1// JavaScript transformer for Adyen transactions response
2const transactions = data.data || [];
3
4return transactions.map(txn => ({
5  psp_reference: txn.id || '',
6  merchant_reference: txn.merchantReference || '',
7  amount: txn.amount?.value ? (txn.amount.value / 100).toFixed(2) : '0.00',
8  currency: txn.amount?.currency || '',
9  status: txn.status,
10  payment_method: txn.paymentMethod || '',
11  created_at: txn.createdAt ? new Date(txn.createdAt).toLocaleString() : '',
12  balance_account_id: txn.balanceAccountId || '',
13  category: txn.category || ''
14}));

Create a dedicated Disputes tab in your Retool app for managing Adyen chargebacks. Click + New in the query panel and select your Adyen Management API resource. Set the method to GET and the path to /disputes. Adyen's Disputes endpoint supports filters: merchantAccountCode, creationDateGte, creationDateLte, and status. Add URL parameters that reference filter components in your app: - merchantAccountCode: {{ retoolContext.configVars.ADYEN_MERCHANT_ID }} - creationDateGte: {{ disputeDateRange.start ? new Date(disputeDateRange.start).toISOString().split('T')[0] : '' }} - status: {{ disputeStatusSelect.value || '' }} (values: open, won, lost, chargedBack, expired) Set the query to Run on page load and when inputs change. Add a JavaScript transformer to extract and format the key fields: PSP reference, reason code, amount, deadline date (the date by which evidence must be submitted), and days remaining until deadline. Drag a Table component onto the Disputes tab. Set its data source to {{ disputesQuery.data }}. Add conditional row colors: red for disputes with deadlines within 3 days (high urgency), yellow for 4-7 days (moderate urgency). Add a column for days remaining calculated from the deadline field. Add two Button components: 'Accept Chargeback' and 'Submit Defense'. The Accept button triggers a POST to /disputes/{{ disputesTable.selectedRow.psp_reference }}/accept. The Submit Defense button opens a Modal component with a TextArea for evidence details and a File Upload component, then triggers a POST to /disputes/{{ disputesTable.selectedRow.psp_reference }}/defend with the evidence payload. Both actions include confirmation modals.

1// JavaScript transformer for Adyen disputes
2const disputes = data.disputes || data || [];
3const now = new Date();
4
5return disputes.map(dispute => {
6  const deadline = dispute.reasonCode?.defenseDeadline 
7    ? new Date(dispute.reasonCode.defenseDeadline) 
8    : null;
9  const daysRemaining = deadline 
10    ? Math.ceil((deadline - now) / (1000 * 60 * 60 * 24))
11    : null;
12
13  return {
14    psp_reference: dispute.pspReference,
15    merchant_reference: dispute.merchantReference || '',
16    reason_code: dispute.reasonCode?.code || '',
17    reason_description: dispute.reasonCode?.description || '',
18    amount: dispute.disputeAmount?.value 
19      ? (dispute.disputeAmount.value / 100).toFixed(2) 
20      : '0.00',
21    currency: dispute.disputeAmount?.currency || '',
22    status: dispute.status,
23    deadline: deadline ? deadline.toLocaleDateString() : 'No deadline',
24    days_remaining: daysRemaining,
25    urgent: daysRemaining !== null && daysRemaining <= 3
26  };
27});

Adyen sends webhook notifications for payment events (authorization, refund, chargeback, capture). To receive and verify these in Retool, create a Workflow with a Webhook trigger that validates Adyen's HMAC signature before processing the event data. Navigate to the Workflows section in Retool (lightning bolt icon in the sidebar). Click New Workflow. Click Add Trigger → Webhook. Retool provides a unique HTTPS URL — copy this URL and configure it in Adyen's Customer Area under Developers → Webhooks → Create new webhook → Standard notification → URL: [paste the Retool Workflow URL]. In Adyen's webhook configuration, also set an HMAC Key. Copy the HMAC key provided by Adyen. Store it in Retool Settings → Configuration Variables as ADYEN_WEBHOOK_HMAC_KEY (secret). In your Retool Workflow, add the first block: a JavaScript Code block. This block validates the HMAC signature from the incoming webhook request. The validation uses HMAC-SHA256 on Adyen's specific signing string format (concatenated fields from the notification) and compares it to the signature in the additionalData.hmacSignature field. Add a Branch block after validation: if the HMAC is valid, proceed to process the event. If invalid, return a 400 response. Add Resource Query blocks to handle the event: update your internal PostgreSQL database with the payment status, trigger a Slack notification for chargebacks, or update a CRM record. Click Publish Release to activate the Workflow. Adyen sends a test notification to verify the endpoint — the Workflow should return a 200 response with body [accepted] to confirm receipt.

1// JavaScript Code block: validate Adyen HMAC webhook signature
2const hmacKey = retoolContext.configVars.ADYEN_WEBHOOK_HMAC_KEY;
3const notification = startTrigger.data;
4
5// Adyen HMAC signing string fields (in this exact order)
6const notificationItem = notification.notificationItems?.[0]?.NotificationRequestItem;
7if (!notificationItem) throw new Error('Invalid notification structure');
8
9const signingString = [
10  notificationItem.pspReference,
11  notificationItem.originalReference || '',
12  notificationItem.merchantAccountCode,
13  notificationItem.merchantReference,
14  notificationItem.amount?.value?.toString() || '',
15  notificationItem.amount?.currency || '',
16  notificationItem.eventCode,
17  notificationItem.success
18].join(':');
19
20// Compute expected HMAC using CryptoJS
21const keyBytes = CryptoJS.enc.Hex.parse(hmacKey);
22const expectedHmac = CryptoJS.HmacSHA256(signingString, keyBytes).toString(CryptoJS.enc.Hex);
23
24const receivedHmac = notificationItem.additionalData?.hmacSignature || '';
25
26if (expectedHmac !== receivedHmac) {
27  throw new Error('HMAC validation failed — webhook rejected');
28}
29
30return {
31  valid: true,
32  eventCode: notificationItem.eventCode,
33  pspReference: notificationItem.pspReference,
34  merchantReference: notificationItem.merchantReference,
35  success: notificationItem.success === 'true'
36};

Add a settlement reconciliation tab to give finance teams visibility into which Adyen payments have settled and how amounts compare to your internal order records. Adyen's settlement reports are available through their Report Download API or through the transaction listing endpoint filtered by category. Create a query using your Adyen Management API resource: GET /merchants/{{ retoolContext.configVars.ADYEN_MERCHANT_ID }}/transactions with body filter { 'statuses': ['settled'], 'dateTimeFrom': '...', 'dateTimeTo': '...' }. Create a parallel query against your internal PostgreSQL (or other database) resource: SELECT order_id, payment_reference, amount, currency, status FROM orders WHERE created_at BETWEEN $1 AND $2 — with date range parameters matching the Adyen query. Create a JavaScript query that joins the two datasets on the merchant reference field (the reference your system passes to Adyen at payment time). Categorize each record as: 'Matched' (found in both with matching amounts), 'Amount mismatch' (found in both but amounts differ by more than 0.01), 'Adyen only' (in Adyen settlement but no internal order), or 'Internal only' (internal order with no Adyen settlement). Drag a Tab component onto the reconciliation section with three tabs: All, Discrepancies, and Matched. Bind each Table to the filtered subset of the joined dataset. Add a 'Flag for Review' button that adds a flag to your internal orders table for the selected row. For complex multi-system reconciliation involving Adyen settlements, internal orders, and ERP systems, RapidDev's team can help design and implement the complete Retool solution with appropriate data validation and export workflows.

1// JavaScript query: reconcile Adyen settlements with internal orders
2const adyenSettlements = adyenSettlementsQuery.data || [];
3const internalOrders = internalOrdersQuery.data || [];
4
5// Build lookup map from internal orders keyed by payment reference
6const orderMap = {};
7internalOrders.forEach(order => {
8  orderMap[order.payment_reference] = order;
9});
10
11// Build lookup map from Adyen settlements keyed by merchant reference
12const adyenMap = {};
13adyenSettlements.forEach(txn => {
14  adyenMap[txn.merchant_reference] = txn;
15});
16
17const results = [];
18
19// Check all Adyen records
20adyenSettlements.forEach(txn => {
21  const internalOrder = orderMap[txn.merchant_reference];
22  const adyenAmount = parseFloat(txn.amount);
23
24  if (!internalOrder) {
25    results.push({ ...txn, match_status: 'Adyen only', internal_amount: null, discrepancy: null });
26  } else {
27    const internalAmount = parseFloat(internalOrder.amount);
28    const discrepancy = Math.abs(adyenAmount - internalAmount);
29    results.push({
30      ...txn,
31      match_status: discrepancy > 0.01 ? 'Amount mismatch' : 'Matched',
32      internal_amount: internalAmount.toFixed(2),
33      discrepancy: discrepancy > 0.01 ? discrepancy.toFixed(2) : null
34    });
35  }
36});
37
38// Add internal-only records
39internalOrders.forEach(order => {
40  if (!adyenMap[order.payment_reference]) {
41    results.push({
42      merchant_reference: order.payment_reference,
43      amount: order.amount,
44      currency: order.currency,
45      match_status: 'Internal only',
46      psp_reference: null,
47      internal_amount: order.amount
48    });
49  }
50});
51
52return results;