Set up QuickBooks Online payroll journals: step by step

1. Before you start

2. In Intuit: create your own QuickBooks app

AhlanHamad connects to QuickBooks through an app your company creates in the Intuit Developer portal and uses only for itself. Test it first with its Development keys and an Intuit sandbox company; switch to its Production keys for your live company once Intuit has reviewed the app. Intuit's steps: create an app, keys and credentials, production keys.

1. Go to developer.intuit.com and sign in, or create a free developer account.
2. Open My Hub → App dashboard (top right), select the app card with a +, and follow the steps. Name the app something you will recognise, for example AhlanHamad payroll.
3. When Intuit asks for permissions (scopes), choose accounting (com.intuit.quickbooks.accounting). Nothing else is needed.
4. In the app's Settings → Redirect URIs tab, add https://ahlanhamad.com/auth/quickbooks/callback under Development, and again under Production, exactly as written: https, same casing, no slash at the end; Intuit requires an exact match (Intuit: redirect URIs). AhlanHamad shows the same address on the Connection tab under “Redirect URI to register on your app”, with a Copy button.
5. Test first with Development keys. Open Keys and credentials → Development and copy the Client ID and Client secret (Intuit: keys). Development keys only reach Intuit sandbox companies, and your developer account comes with one (Intuit sandboxes). You paste them in section 4.
6. Then get Production keys for your live company. Intuit shows them only after two steps (Intuit: go live): App details (contact email, end-user licence agreement and privacy policy links, host domain, launch, disconnect and connect/reconnect URLs, categories, regulated industries, hosting regions; Intuit says about 30 minutes) and the Compliance questionnaire. If a field asks for our addresses: host domain ahlanhamad.com, launch URL https://ahlanhamad.com/en/integrations/quickbooks.
7. Once Intuit has approved the questionnaire, open Keys and credentials → Production, turn on Show credentials and copy the Client ID and Client secret. Keep the secret private; AhlanHamad stores both encrypted.

3. In QuickBooks: get your chart of accounts ready

Payroll journals post totals to your own accounts, and QuickBooks refuses Accounts payable (A/P) and Accounts receivable (A/R) on them (they need a vendor or customer on every line). So create the liability accounts you need first. In QuickBooks, go to Settings ⚙ → Chart of accounts → New. Testing with Development keys? Do the same in your sandbox company.

1. If you have no ordinary liability for net salaries, add one: account type Other Current Liabilities, name for example Salaries payable.
2. Do the same for social insurance payable (and, if used, deductions withheld and DIFC DEWS payable): Other Current Liabilities accounts.
3. Add the end-of-service provision as a Long Term Liabilities account, if you don't have one.
4. Only if you prefer not to post the salary payment straight to your bank account: add an Other Current Liabilities account such as Salary clearing (section 5 explains when).

4. In AhlanHamad: connect QuickBooks Online

Go to Integrations, open QuickBooks Online and stay on the Connection tab. The card starts with Connect with your own QuickBooks app, with a link to this guide.

1. Check the address under Redirect URI to register on your app is the one you added in section 2.
2. Under Which keys are these? choose Development keys — an Intuit sandbox company (for testing) or Production keys — your live QuickBooks company, to match the keys you are about to paste.
3. Client ID and Client Secret: paste the keys from section 2. Under the secret it says “Stored encrypted on the server. Never shown again and never sent to the browser.”
4. Click Connect to QuickBooks. AhlanHamad says “Taking you to Intuit to sign in…” and opens Intuit.
5. Sign in to Intuit as the QuickBooks admin, choose the company (with Development keys, your sandbox company), and approve the connection.
6. You come back to a page that says Connected to QuickBooks Online, then to the QuickBooks page. The card now shows Connected to QuickBooks Online, Company: with your company's name, “Connected through your own app” (with Development keys, followed by “Sandbox (test) company”), and the Realm ID (QuickBooks' number for your company).

Your app's Client ID and Secret stay saved. If you connect again later, the card says “Your app credentials are saved. Click Connect to sign in with them — no need to enter them again.” To use other keys, click Replace credentials.

Or one click with Ahlan Hamad's app (when available)

AhlanHamad also has its own QuickBooks app. Where it is switched on for your workspace, the Connection tab shows Or connect with Ahlan Hamad's app under the form: you sign in to Intuit and approve access, with no app or keys of your own. Click Connect with Ahlan Hamad's app; the card then says “Connected through Ahlan Hamad's app”. Your own app stays the main way to connect.

5. Check the environment, then map your accounts

1. Open the Field Mapping tab. The card is called Post payroll journals to QuickBooks Online.
2. QuickBooks environment follows the keys you connected with: Sandbox for Development keys, Production for Production keys. It can't be changed here: “This environment was set when QuickBooks was connected (Development or Production keys), so it's fixed here. Reconnect to change it.”
3. Click Load my accounts. This reads your chart of accounts, company name and home currency from QuickBooks. The card then shows Posting to your company and its Base currency.
4. Map each Ahlan Hamad account to a QuickBooks Online account (table below). Some are pre-selected and marked Suggested when the match is clear; check every one with your accountant.
5. Click Save mapping. When nothing is missing the card says Mapping complete. Until then it says “Posting is on hold until every required account is mapped.”
6. If you pay any payroll in a currency other than your QuickBooks home currency, decide on Post runs in other currencies (section 6).

Which QuickBooks account for each payroll account

• Costs go to expense accounts (QuickBooks type Expenses).
• What you owe goes to Other Current Liabilities. The end-of-service provision is the one long-term liability (Long Term Liabilities). Create a “Salaries payable” liability account in QuickBooks first if you don't have one.
• Accounts payable (A/P) and Accounts receivable (A/R) can't be picked. They are greyed out and tagged “A/P — needs a vendor per line” or “A/R — needs a customer per line”: QuickBooks needs a vendor or customer on every line posted there, and payroll journals post totals only.
• The payment goes to the bank account, or to a clearing account. If your bank is connected to QuickBooks, the salary payment will also arrive in the bank feed: match it to the journal entry we posted instead of adding it again, so the bank is not reduced twice. If you prefer, map 1101 to a “Salary clearing” Other Current Liabilities account and categorise the bank-feed payment to that account.

6. What gets posted, and when

• Each journal is one journal entry in QuickBooks, saved straight away (journal entries have no draft state), with one line per account. Its Journal no. is our marker (AH followed by 12 letters and digits); its Memo starts with the description and says “Posted by Ahlan Hamad payroll.”
• We never edit or delete a journal in QuickBooks Online. Corrections are always new journals: the reversal first, then the corrected run as a new journal.
• Each journal is sent once. If a send is cut off halfway, the next try looks the journal up by its marker instead of creating a second one.
• Amounts are in your QuickBooks Online base currency. A run in another currency is held unless you switch on Post runs in other currencies; then it is converted at AhlanHamad's daily exchange rate, and the rate is written on the journal.
• Runs finalized or paid before you saved the mapping are not sent on their own. Open each run and press Send this run's journals. The mapping card lists them under “Earlier runs not sent to QuickBooks Online yet”.
• End-of-service months booked before you connected are listed on the mapping card. Press Send them, check the list of months and amounts, and confirm. They go oldest first, each dated at its own month end.

7. Check your first payroll in QuickBooks

1. In AhlanHamad, open the payroll run. The QuickBooks Online journals card lists each journal (Payroll accrual, Salary payment, …) with its status. Posted means QuickBooks has it, and the card shows its journal number, for example Journal AH1F2E3D4C5B6A.
2. In QuickBooks, open Reports, search for Journal, run the Journal report for the payroll month, and find the entry with that journal number (Intuit help). The search (magnifying glass) at the top can also find a transaction by its number.
3. Check: the date (the last day of the payroll month for the accrual), the Journal no., one line per mapped account, totals that match the payroll run in AhlanHamad, and the memo.
4. After the run is paid, check the Salary payment entry the same way, and match it to your bank as described in section 5.

8. Troubleshooting

Company admins who can manage settings, and finance managers, also get an in-app notice and an email when QuickBooks Online journals are held or fail: one per problem, a reminder after three days, and a short note when it clears. No amounts, names or QuickBooks Online errors are put in the email; open the payroll run to see the reason.

When connecting (Connection tab and the return page)

When loading your accounts (Field Mapping tab)

On the payroll run: On hold

A held journal is waiting, not lost. Fix the reason and it goes, either by itself or when you press Retry on the run card.

On the payroll run: Failed

These come back from QuickBooks Online, in English, with QuickBooks Online's own words added after ours. Fix the cause in QuickBooks Online or in the mapping, then press Retry. A retry never creates a second journal.

On the payroll run: Not needed

Two accounting systems

If the QuickBooks Online page or the payroll run says “Payroll is being posted to …” with more than one system, every run is booked in each of them. If you keep your books only in QuickBooks Online, disconnect the others so payroll costs aren't counted twice.

9. Disconnecting

1. In AhlanHamad, go to Integrations → QuickBooks Online → Connection and click Disconnect QuickBooks. AhlanHamad deletes the stored connection and also revokes its access at Intuit.
2. If you won't use your Intuit app again, you can delete it in the Intuit Developer portal too.

• Journals already in QuickBooks Online stay there. We never delete or change them.
• While QuickBooks Online is disconnected, new payroll journals are not sent. The run card says “QuickBooks Online is not connected, so new journals are not being sent.”
• If you connect again later, open each payroll run from that time and press Send this run's journals, and send any end-of-service months listed on the mapping card.

Intuit sources used in this guide

• Intuit Developer: create an app, keys and credentials, redirect URIs, going live, sandbox companies, JournalEntry API.
• QuickBooks Online help: journal entries, closing the books.
• QuickBooks and Intuit are trademarks of Intuit Inc. AhlanHamad is not affiliated with Intuit.