QuickBooks Online and Adyen integration

What moves between them

Payment data flows from Adyen into QuickBooks Online on a real-time basis. When Adyen records a CAPTURE event (indicating a settled payment), ml-connector reads the capture amount, associated customer, and payment method, and posts a journal entry into QuickBooks Online allocating the payment to the appropriate income account and the matching customer's linked deposit account. Refund events (REFUND) trigger offsetting journal entries in QuickBooks Online. Disputed transactions (CHARGEBACK, PREARBITRATION_LOST) are logged to a custom field or audit record in QuickBooks Online so the accounting team can track which payments are in dispute. The sync runs on each webhook event from Adyen, so entries appear in QuickBooks Online within seconds of settlement.

How ml-connector handles it

ml-connector stores the Adyen API key encrypted and the QuickBooks OAuth token (refreshed before it expires). On each Adyen webhook, it validates the HMAC-SHA256 signature using the webhook signing key to ensure the request is genuine, then extracts the payment or dispute details. It looks up the customer in QuickBooks Online by matching Adyen's customer reference to a QuickBooks Online custom field or note, and retrieves the income account and deposit account from the configured mapping. For CAPTURE events, it builds a journal entry with two lines: debit to the deposit account (bank) for the net settlement amount, and credit to the income account for the gross amount, with any fees or currency differences posted to a configured fees account. The journal entry includes the Adyen transaction ID and timestamp so the entry can be reconciled and replayed if the write fails. For REFUND events, it reverses the original entry by posting the refund amount in the opposite direction. All entries carry a full audit trail with the event timestamp, Adyen transaction ID, and ml-connector job ID for replay and debugging.

A real-world example

A small online retailer uses QuickBooks Online to manage invoicing and accounts and Adyen to process credit card and digital wallet payments on their web store. Before the integration, the owner received daily settlement reports from Adyen, manually matched customers and amounts in a spreadsheet, and re-entered the net deposits into QuickBooks Online each day, which took about 30 minutes and was prone to errors when customers applied the same invoice multiple times or when fees differed from the quoted percentage. With QuickBooks Online and Adyen connected, each payment from Adyen posts automatically into QuickBooks Online within seconds, reconciled to the right customer and account. The daily deposit is never forgotten, and month-end reconciliation is simply a review of the audit trail in ml-connector and a balance check in QuickBooks Online.

What you can do

• •Post every settled Adyen payment into QuickBooks Online as a journal entry, allocated to the correct income and deposit accounts.
• •Track refunds and cancellations by reversing the original journal entry in QuickBooks Online.
• •Record disputed transactions in QuickBooks Online so the accounting team can investigate without manual lookup.
• •Validate HMAC signatures on every Adyen webhook and refresh the QuickBooks OAuth token before it expires.
• •Handle mapping of Adyen customers to QuickBooks Online customer IDs and reconcile all entries with a full audit trail for replay.

Questions

Do payments move in both directions between QuickBooks Online and Adyen?

No. Payments flow from Adyen into QuickBooks Online. Adyen does not accept payment data from QuickBooks Online - it is a payment processor, not a financial ledger. ml-connector reads settled payments, refunds, and disputes from Adyen and writes them as journal entries into QuickBooks Online.

How does ml-connector know which QuickBooks Online account to post a payment to?

You configure a mapping of Adyen merchants or payment methods to QuickBooks Online income and deposit accounts. ml-connector looks up the customer in QuickBooks Online by matching an Adyen customer reference (like an order ID) to a custom field or note in the QuickBooks Online customer record, then uses the mapped accounts for the journal entry.

What happens if the QuickBooks OAuth token expires or an Adyen webhook signature is invalid?

ml-connector refreshes the QuickBooks OAuth token before it expires (token TTL is 1 hour, refresh is automatic). For Adyen webhooks, every request is validated using HMAC-SHA256 with the webhook signing key - a bad signature causes the webhook to be rejected, logged, and retried by Adyen. The full audit trail allows you to replay any failed entry once the issue is fixed.