Setup guide · Zoho Books payroll journals · Early access
Set up Zoho Books payroll journals: step by step
This guide is for two people working together: your Zoho Books admin, who creates the Zoho API client and knows your chart of accounts, and the person who runs payroll in AhlanHamad, who connects Zoho Books and maps the accounts. Follow it in order. Every AhlanHamad label below is the one you will see on screen.
Updated 12 October 2026
1. Before you start
Early access. Posting payroll journals to Zoho Books is switched on one company at a time, when you ask us. It is not open to every company yet. Until it is on for your company, the Field Mapping tab says “Posting payroll journals to Zoho Books isn't switched on for your workspace yet.”
| Check | What you need |
|---|---|
| Zoho Books plan | A plan with journals and API access. Zoho's pricing page lists API Access from the Standard plan up (the Free plan has journals, but its API access is not listed there), so use Standard or higher (Zoho Books pricing). Zoho also caps API calls per day by plan (Standard 2,000); a company's payroll journals use few. |
| Where it stands | Tested end to end on one real Zoho Books organisation in the zoho.ae data centre (AED): the payroll accrual, the salary payment, a held journal released after its account was mapped, and the reversal of a deleted run. It has not yet been tried in zoho.sa or the other data centres, nor for a customer, and the one-click connection (section 3) has not yet been run against a live Zoho account, so check your first journals closely and tell us if anything looks wrong. |
| Your Zoho data centre | The domain you sign in to Zoho on: zoho.com, zoho.sa, zoho.ae, zoho.eu, zoho.in, zoho.com.au, zoho.jp or zohocloud.ca. Look at the address bar while you are in Zoho Books (Zoho Books API). Accounts opened in Kuwait, Qatar, Bahrain or Oman are usually on zoho.com. |
| Currency and decimals | Journals are posted in the organisation's base currency. Zoho Books keeps each currency's own number of decimals, set by your organisation (Settings → Currencies, Zoho help). For KWD, BHD or OMR set it to 3, or the third decimal may be rounded. |
| A Zoho Books admin | Creates the Zoho API client and signs in to approve the connection. |
| In AhlanHamad | A company admin who can manage settings (to connect Zoho Books and save the mapping), and the person who finalizes and pays payroll. Your accountant should help with the mapping. |
Only totals are sent to Zoho Books: one line per account, never a line per employee. Names, IDs and individual salaries stay in AhlanHamad (the journal's description carries the number of employees in the run, nothing more).
2. In Zoho: create your Zoho API client
AhlanHamad connects to Zoho Books through a client your company creates in the Zoho API Console and uses only for itself. (Where one-click connection with AhlanHamad's own Zoho client is switched on for your workspace, you can use that instead and skip this section; section 3 explains.) Create the client in the console of your data centre: for example api-console.zoho.com, api-console.zoho.sa or api-console.zoho.ae (Zoho: OAuth setup).
- Sign in to the API Console of your data centre with your Zoho Books admin account.
- Click GET STARTED (or ADD CLIENT if you already have clients) and choose Server-based Applications → CREATE NOW.
- Client Name: for example
AhlanHamad payroll. Homepage URL:https://ahlanhamad.com. Authorized Redirect URIs:https://ahlanhamad.com/auth/zoho-books/callback, exactly as written. Click CREATE. - Open the Client Secret tab and copy the Client ID and Client Secret. You paste both in section 3; AhlanHamad stores them encrypted.
- If your Zoho sign-in reaches more than one Zoho Books organisation, you can note the Organization ID of the one you keep payroll in (in Zoho Books, click your organisation's name, top right → Manage Organizations), or choose it in AhlanHamad after signing in (section 3).
Testing first? The same client works for a trial or test Zoho Books organisation in the same data centre. Connect to that first, then reconnect with your live organisation's Organization ID.
3. In AhlanHamad: connect Zoho Books
Go to Integrations and open Zoho Books. Stay on the Connection tab. The card starts with Connect with your own Zoho app, with a link to this guide.
With your own Zoho client
- Client ID and Client Secret: paste the values from section 2.
- Zoho data centre: choose the domain you sign in on. It is pre-selected from your company's country (Saudi Arabia
zoho.sa, UAEzoho.ae, otherwisezoho.com); change it if yours differs. The note says “Sign-in and every Zoho Books call go to this data centre.” - Organization ID: leave it empty if you have one Zoho Books organisation; it is found after sign-in. If you have several, enter the ID from section 2, or leave it empty and choose the organisation after sign-in.
- Check the address under Redirect URI to register on your app is the one on your Zoho client.
- Click Connect to Zoho Books. AhlanHamad says “Zoho OAuth initiated — complete sign-in in the redirect window” and opens Zoho.
- Sign in to Zoho and accept the access Zoho Books asks for.
- You come back to a page that says Connected to Zoho Books, then to the Zoho Books page. The card shows Connected to Zoho Books, the Organisation name, the Organization ID, the Zoho data centre and “Connected through your own app”. If your sign-in reaches several organisations and none was given, the card asks you to Choose your Zoho Books organisation (“Your Zoho sign-in reaches more than one organisation. Choose the one payroll journals go to. Nothing is posted until you do.”): pick it and click Use this organisation.
Your client's 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 a different client, click Replace credentials.
Or one click with Ahlan Hamad's app (when available)
Where AhlanHamad's own Zoho client is switched on for your workspace, the Connection tab shows Or connect with Ahlan Hamad's app under the form: “Connect in one click: you sign in to Zoho, approve access and pick your Zoho Books organisation. No Zoho API client or keys needed, and you don't need to know your Zoho data centre — Zoho tells us.”, with What Ahlan Hamad will access. Click Connect with Ahlan Hamad's app, sign in and approve; choose the organisation if asked, as above. The card then says “Connected through Ahlan Hamad's app”. Your own client stays the main way to connect.
Already sending payroll to another accounting system? If another one is connected and receiving payroll, AhlanHamad asks first: “Connect a second accounting system?” If you connect Zoho Books too, every payroll run is posted to both and your payroll costs are booked twice. If you are moving to Zoho Books, click Cancel, disconnect the other system first, then connect Zoho Books.
4. Map your accounts
- Open the Field Mapping tab. The card is called Post payroll journals to Zoho Books.
- Zoho data centre shows the one you connected in, locked: “Set by your Zoho Books connection. To use a different data centre, reconnect Zoho Books on the Connection tab.”
- Click Load my accounts. This reads your chart of accounts, organisation name and base currency from Zoho Books. The card then shows Posting to your organisation and its Base currency.
- Map each Ahlan Hamad account to a Zoho Books account (table below). Some are pre-selected and marked Suggested when the match is clear; check every one with your accountant.
- 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.”
- If you pay any payroll in a currency other than your Zoho Books base currency, decide on Post runs in other currencies (section 5).
Which Zoho Books account for each payroll account
| Code | Ahlan Hamad account | Needed | Typical Zoho Books account type |
|---|---|---|---|
| 5100 | Salaries — basic, other allowances, overtime & additions | Required | Expense |
| 5400 | Housing allowance | Required | Expense |
| 5500 | Transport allowance | Required | Expense |
| 5200 | Employer social-insurance contribution | Required | Expense |
| 5300 | End-of-service expense | Required | Expense |
| 2100 | Net salaries payable | Required | Other Current Liability (not Accounts Payable) |
| 2200 | Social insurance payable (employee + employer) | Required | Other Current Liability |
| 2300 | End-of-service provision | Required | Long Term Liability |
| 1101 | Bank account salaries are paid from | Required | Bank, or a clearing account (see tip) |
| 2700 | Deductions withheld (loans, penalties, unpaid leave) | Only if used | Other Current Liability |
| 5810 | Bank transfer charges on salaries | Only if used | Expense |
| 5310 | DIFC DEWS employer contribution | Only if used | Expense |
| 2310 | DIFC DEWS payable | Only if used | Other Current Liability |
| 5900 | Foreign-exchange gain/loss on payroll (only if a run in another currency is paid at a different rate) | Only if used | Your exchange gain or loss account |
- Costs go to Expense accounts.
- What you owe goes to Other Current Liability accounts. The end-of-service provision is the one Long Term Liability.
- Accounts Payable and Accounts Receivable can't be picked. AhlanHamad says why: “Accounts Payable and Accounts Receivable can't be picked: Zoho Books needs a vendor or customer on every line posted there, and payroll journals post totals only. Pick a liability or clearing account instead.”
- The payment goes to the bank account, or to a clearing account. If your bank feeds into Zoho Books, match the salary payment in the feed to the journal we posted instead of adding it again, so the bank is not reduced twice. Or map 1101 to a “Salary clearing” Other Current Liability account and categorise the bank-feed payment to it.
End-of-service is not on the payroll journal. It is its own journal each month (5300 End-of-service expense / 2300 End-of-service provision).
5. What gets posted, and when
| When this happens in AhlanHamad | Zoho Books receives | Dated |
|---|---|---|
| A payroll run is finalized (Finalize) | Payroll accrual: salaries and allowances, employer social insurance and the payables they create (debits 5100–5500, credits 2100, 2200 and, if used, 2700) | The last day of the payroll month |
| The run is paid (Mark as Paid, or CEO Sign-off & Pay) | Salary payment: debit 2100 Net salaries payable, credit 1101 | The day the run was signed off and paid |
| Bank transfer charges are recorded on a paid run | Bank charges: debit 5810, credit 1101 | The pay day |
| A month ends | End-of-service accrual: debit 5300, credit 2300 — sent automatically on the 1st of the next month. You can also run it by hand for a finished month with Run Monthly Accrual on the Finance page. | The last day of that month |
| A run is deleted, or a posted journal is corrected | A reversal: a new journal with the same lines, debit and credit swapped. Zoho Books does not link the two; the reversal's notes start with “Reversal of” and the reference it reverses. A corrected run is then posted again as a new journal. | The day of the change |
- Each journal is one manual journal in Zoho Books, created and then published (not left as a draft), with one line per account (Zoho journals API). Its Reference# is our marker (
AHfollowed by 12 letters and digits); its Notes start with the description and say “Posted by Ahlan Hamad payroll.” Zoho gives it its own Journal#. - We never edit or delete a journal in Zoho Books. 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 Zoho Books 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 Zoho Books 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.
Every journal's description starts with what it is and AhlanHamad's own reference for it: PAY-KW-2026-10 for the October 2026 Kuwait payroll accrual, PAY-KW-2026-10-PMT for its salary payment, PAY-KW-2026-10-FEES for its bank charges, IND-KW-2026-10 for that month's end-of-service accrual (the country code is the run's own). A reversal's description starts with “Reversal of” and the reference it reverses. Each journal also carries a marker: AH followed by 12 letters and digits.
6. Check your first payroll in Zoho Books
- In AhlanHamad, open the payroll run. The Zoho Books journals card lists each journal (Payroll accrual, Salary payment, …) with its status. Posted means Zoho Books has it, and the card shows Zoho's journal number, for example
Journal 25. - In Zoho Books, go to Accountant → Manual Journals (Zoho help).
- Find the journal by that Journal#, or by its Reference# (
AH…) and date. - Open it and check: the status Published, the date (the last day of the payroll month for the accrual), one line per mapped account, totals that match the payroll run in AhlanHamad, and the notes.
- After the run is paid, check the Salary payment journal the same way, and match it to your bank as described in section 4.
Statuses on the run card: Queued and Sending (on its way), Waiting (another journal must reach Zoho Books first), Retrying (Zoho Books or the network was busy; we try again automatically), Posted, On hold (needs you; the reason is shown), Failed (Zoho Books refused it; the reason is shown), Not needed (nothing to send; the reason is shown).
7. Troubleshooting
Company admins who can manage settings, and finance managers, also get an in-app notice and an email when Zoho Books journals are held or fail: one per problem, a reminder after three days, and a short note when it clears. No amounts, names or Zoho Books errors are put in the email; open the payroll run to see the reason.
When connecting (Connection tab and the return page)
| What you see | What to do |
|---|---|
| Enter your app's Client ID and Client Secret to connect. | Paste both values from your app (own-app connection only), then click Connect. |
| Enter both the Client ID and the Client Secret to replace the saved credentials. | You started replacing the saved credentials: fill in both fields, or click Keep saved credentials. |
| Connecting isn't available yet: this workspace's app address isn't configured. Contact support and we'll set it up. | Contact us. Nothing on your side is wrong. |
| Couldn't connect Zoho Books — with “No authorization code was returned. The connection was cancelled or the link is invalid.” | You cancelled or declined on the Zoho Books screen, or the link was opened twice. Start again from the Connection tab. |
| You were signed out before the connection finished. Sign in again, then reconnect from the integration settings. | Sign in to AhlanHamad, then click Connect again. Use the same browser for the whole flow. |
| This connection link is invalid, expired or already used. Start the connection again from the integration's settings page. | Each connect link works once and for a short time. Click Connect again on the Connection tab. |
| Token exchange failed: … | Zoho Books refused to hand over the connection: usually the Client Secret is wrong, or the redirect URI on your app does not match exactly. Check both (own-app connection), then connect again. |
| No stored Zoho Books credentials for this company. Run Connect first. | Your client's keys were not saved. Paste the Client ID and Client Secret again and click Connect to Zoho Books. |
| Zoho token error: … | Zoho refused the client: most often it was created in another data centre's API Console than the Zoho data centre you chose. Choose the data centre whose console holds the client (or create the client in your data centre's console), then connect again. |
| Zoho shows an error page instead of the sign-in, mentioning the redirect URI | The redirect URI on your Zoho client does not match. Set Authorized Redirect URIs to https://ahlanhamad.com/auth/zoho-books/callback exactly as written, then connect again. |
| Your Zoho sign-in doesn't reach any Zoho Books organisation. | The Zoho user you signed in with has no Zoho Books organisation in that data centre. Sign in with your Zoho Books admin, or check the data centre, then connect again. |
| Zoho Books needs to be reconnected — with “Zoho Books no longer accepts the saved connection: access was revoked or has expired. Journals are held, not lost. Connect again below and sign in, and the held journals are sent automatically.” | Click Reconnect and sign in again. Held journals are sent by themselves once you are back. |
When loading your accounts (Field Mapping tab)
| What you see | What to do |
|---|---|
| Choose the Zoho Books data centre your account lives in, then load your accounts. | A connection made before the data centre was recorded: choose it under Zoho data centre on the mapping card, then Load my accounts. |
| Zoho Books needs to be reconnected: access was revoked or has expired. Reconnect Zoho Books from Integrations. | Click Reconnect on the Connection tab and sign in to Zoho again. |
| Zoho Books did not report the organisation's base currency. | Check the organisation's base currency in Zoho Books (Settings → Currencies), then load your accounts again. If it keeps happening, contact us. |
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.
| What you see | What to do |
|---|---|
| Map these accounts first: 5400, 5500. | Map the listed account codes on the Field Mapping tab and click Save mapping, then Retry. |
| Load your accounts and save the mapping on the integration page first. | On the Field Mapping tab, click Load my accounts, save the mapping, then Retry. |
| … mapped to an account that can't be used in a journal (Accounts Payable or Receivable, a system or bank account, or an account with no code). Pick another account on the integration page. | In Zoho Books terms: an Accounts Payable or Accounts Receivable account. Map those codes to an Other Current Liability account (or another suitable account), save, then Retry. |
| This run's currency differs from your books. Allow other-currency posting to send it. | Switch on Post runs in other currencies on the Field Mapping tab, then Retry. Or keep that run out of Zoho Books. |
| The connection needs to be renewed. Reconnect and try again. | Zoho stopped accepting the connection: the client was deleted in the API Console, access was removed in Zoho, or the admin who approved it lost access. Click Reconnect on the Connection tab and sign in again (the same client is reused). Journals held for this reason are sent automatically once you reconnect. |
| Not connected, or posting is switched off. | Connect Zoho Books again on the Connection tab. Held journals are sent automatically once you reconnect. If Zoho Books is connected and you still see this, ask us: posting may have been switched off for your company. |
On the payroll run: Failed
These come back from Zoho Books, in English, with Zoho Books's own words added after ours. Fix the cause in Zoho Books or in the mapping, then press Retry. A retry never creates a second journal.
| What you see | What to do |
|---|---|
| Zoho Books rejected the journal (400). followed by Zoho Books's own message | Read Zoho's message after ours (it starts with Zoho's code in brackets). A common one: the date falls in a locked period (Accountant → Transaction Locking, Zoho help). Ask your accountant to unlock it, or reverse and correct the run in AhlanHamad. |
| Zoho Books refused access (403). The connection may lack permission to post journals, or the organisation was disconnected — reconnect Zoho Books. | The Zoho Books user you signed in with can't create journals in that company. Sign in again with a user who can (an admin), then Retry. |
| Zoho Books could not find the company or an account this journal points at (404). Check the account mapping belongs to the connected company. | A mapped account was deleted or archived in Zoho Books. Click Reload accounts, fix the mapping, save, then Retry. |
| This run's payroll accrual journal did not reach Zoho Books. Retry the accrual first, then retry this payment, so it clears exactly the salaries payable the accrual booked. | Retry the Payroll accrual line first, then the Salary payment line. |
| No exchange rate from … to … is available. | Try again later, or contact us. |
| … — gave up after 6 attempts. | Zoho Books or the network kept failing. Check Zoho Books opens normally, then press Retry. |
| Created as a draft but not published: … | The journal is in Zoho Books as a draft and Zoho refused to publish it; the reason follows. Fix it, then Retry: the same draft is published, never a second one. |
On the payroll run: Not needed
| What you see | What it means |
|---|---|
| Reversed in Ahlan Hamad before it reached Zoho Books; the pair nets to zero. | Nothing to do: the journal and its reversal cancel out, so neither is sent to Zoho Books. |
| Reverses an entry that never reached Zoho Books, so there is nothing to reverse there. | Nothing to do. |
Two accounting systems
If the Zoho Books 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 Zoho Books, disconnect the others so payroll costs aren't counted twice.
8. Disconnecting
- In AhlanHamad, go to Integrations → Zoho Books → Connection and click Disconnect Zoho Books. AhlanHamad deletes the stored connection and also revokes its access at Zoho.
- If you connected with your own Zoho client and won't use it again, you can delete it in the Zoho API Console too.
- Journals already in Zoho Books stay there. We never delete or change them.
- While Zoho Books is disconnected, new payroll journals are not sent. The run card says “Zoho Books 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.
Zoho sources used in this guide
- Zoho Accounts: creating an OAuth client, multiple data centres.
- Zoho Books API: introduction, data centres and organisation id, journals.
- Zoho Books: pricing and plans, manual journals, transaction locking, decimal places.
- Zoho and Zoho Books are trademarks of Zoho Corporation. AhlanHamad is not affiliated with Zoho.