Setup guide · Business Central payroll journals · Coming soon

Set up Dynamics 365 Business Central payroll journals: step by step

This guide is for two people working together: your Microsoft 365 or Business Central admin, who registers the app and adds it in Business Central, and the person who runs payroll in AhlanHamad, who connects it and maps the accounts with your accountant. Follow it in order. Every AhlanHamad label below is the one you will see on screen.

Updated 12 October 2026

1. Before you start

Coming soon. Posting payroll journals to Business Central is switched off. You can do the Microsoft side (sections 2 and 3) now; the Dynamics 365 Business Central page appears under Integrations once we switch it on for your company.

Check	What you need
Where it stands	Built against Microsoft's Business Central API v2.0, and tested only against a simulated Business Central. It hasn't posted to a real Business Central environment yet, so start in a sandbox environment and check your first journals closely.
Business Central	Business Central online (the cloud version). This is not Dynamics 365 Finance & Operations, which has its own connect-only page.
Currency and decimals	Journals are posted in the company's local currency (the LCY Code in General Ledger Setup). For KWD, BHD or OMR, check that Amount Rounding Precision there is `0.001`, or three-decimal amounts may be refused (Microsoft Learn).
A Microsoft admin	Someone who can register apps in the Microsoft Entra admin center, and an admin who can grant consent (for example a Global Administrator). Also a Business Central user who can add the app on the Microsoft Entra Applications page and create a journal batch.
In AhlanHamad	A company admin who can manage settings (to connect and save the mapping), and the person who finalizes and pays payroll. Your accountant should help with the mapping.

Only totals are sent to Dynamics 365 Business Central: 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 Microsoft Entra: register your app

Business Central lets an integration that runs without a person signed in use service-to-service authentication: your own app, with an application permission (Microsoft Learn: service-to-service authentication). Sign in to the Microsoft Entra admin center.

Go to Entra ID → App registrations → New registration. Name: for example AhlanHamad payroll. Supported account types: Single tenant only (your own organisation). No redirect URI is needed. Click Register (Microsoft Learn: register an application).
On the app's Overview, copy the Application (client) ID and the Directory (tenant) ID (find your tenant ID).
Certificates & secrets → Client secrets → New client secret: add a description, pick an expiry (at most 24 months) and click Add. Copy the Value straight away: Microsoft never shows it again (Microsoft Learn: add credentials). Note the expiry date: when it passes, posting stops until you reconnect with a new secret.
API permissions → Add a permission → Microsoft APIs → Dynamics 365 Business Central → Application permissions → tick API.ReadWrite.All → Add permissions. AhlanHamad uses Business Central's standard API only, so Automation.ReadWrite.All is not needed.
Click Grant admin consent for <your organisation> and confirm. The Status must show Granted (Microsoft Learn: grant admin consent).

3. In Business Central: add the app and a journal batch

Add the app

In Business Central, search (Alt+Q) for Microsoft Entra Applications and choose New. The Microsoft Entra Application Card opens.
Client ID: the Application (client) ID from section 2. Description: for example AhlanHamad payroll journals. State: Enabled.
Under User Permission Sets, give the app what it needs, in each company payroll goes to: read companies, G/L accounts, General Ledger Setup and journal batches, and create, delete and post general journal lines. Microsoft asks for least privilege and doesn't allow the SUPER set for apps (Microsoft Learn). If your partner has no narrower set ready, D365 BUS FULL ACCESS covers it.
You don't need Grant Consent on this card: consent was granted in section 2.

Create a journal batch for AhlanHamad

Search for General Journals. In the Batch Name field, open the list of batches and choose New (Microsoft Learn: general journals).
Name: for example AHPAYROLL. Description: AhlanHamad payroll. Leave No. Series empty: AhlanHamad writes its own document number on every line, and Microsoft says a batch with a number series requires document numbers in its own sequence.
Use this batch for AhlanHamad only. Posting a batch posts every line in it, so AhlanHamad refuses a batch that holds anyone else's lines instead of posting them.

AhlanHamad lists the batches Business Central's API returns for the company (journals API). Create the batch under your usual general journal template; if it doesn't appear in the list in section 5, tell us which template it is in.

Finally, note your environment name: in the Business Central admin center (Settings → Admin Center in Business Central), the Environments tab lists each environment by Name, for example Production or Sandbox (Microsoft Learn: environments).

4. In AhlanHamad: connect Business Central

Go to Integrations and open Dynamics 365 Business Central. Stay on the Connection tab; the card is called Connect Business Central, and Before you connect repeats sections 2 and 3 in short.
Microsoft Entra tenant: the Directory (tenant) ID, or your primary domain such as contoso.onmicrosoft.com.
Environment name: exactly as the admin center shows it, for example Production or Sandbox. Start with a sandbox.
Client ID and Client Secret: the values from section 2. The secret is “Stored encrypted on the server. Never shown again and never sent to the browser.”
Click Connect. AhlanHamad asks Microsoft Entra for a token and lists the environment's companies. When both work it says “Connected to Business Central. Pick the company and journal batch on the Field Mapping tab.”, and the card shows Connected to Business Central with the environment and tenant.

Your app's ID and secret stay saved. To use a new secret (for example when the old one expires), click Replace credentials, enter both values and click Reconnect. Connecting to a different tenant or environment forgets the saved company, journal batch and mapping.

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 Dynamics 365 Business Central too, every payroll run is posted to both and your payroll costs are booked twice. If you are moving to Dynamics 365 Business Central, click Cancel, disconnect the other system first, then connect Dynamics 365 Business Central.

5. Pick the company and batch, and map your accounts

Open the Field Mapping tab. The card is called Post payroll journals to Dynamics 365 Business Central.
Click Load my accounts. If the environment has more than one company, Choose the company asks which one payroll journals go to.
General journal batch: choose the batch from section 3. Until one is chosen the card says “Posting is on hold until a journal is chosen.”
Map each Ahlan Hamad account to a Dynamics 365 Business Central account (table below). Some are pre-selected and marked Suggested when the match is clear; check every one with your accountant.
Click Save mapping. Until every required account is mapped the card says “Posting is on hold until every required account is mapped.”
If you pay any payroll in a currency other than the company's local currency, decide on Post runs in other currencies (section 6).

Which G/L account for each payroll account

Code	Ahlan Hamad account	Needed	Typical Business Central account category
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	Liabilities
2200	Social insurance payable (employee + employer)	Required	Liabilities
2300	End-of-service provision	Required	Liabilities
1101	Bank account salaries are paid from	Required	Assets (cash or bank G/L account, Direct Posting on)
2700	Deductions withheld (loans, penalties, unpaid leave)	Only if used	Liabilities
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	Liabilities
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

Only Posting accounts with Direct Posting on can be picked. AhlanHamad says why: “Accounts with Direct Posting off (such as customer and vendor control accounts) can't be picked: Business Central takes no journal line on them. Headings, totals and blocked accounts aren't listed.”
The payment goes to a G/L account, not a bank account card. Lines are posted with the account type G/L Account. Map 1101 to the G/L account your bank posts to (with Direct Posting on), or to a “Salary clearing” liability that you clear when you reconcile the bank. A bank's G/L account often has Direct Posting off (it is posted through the bank account card); then use the clearing account.
Dimensions (cost centres, departments) are not sent.

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).

6. What gets posted, and when

When this happens in AhlanHamad	Dynamics 365 Business Central 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, under its own document number. A corrected run is then posted again as a new journal.	The day of the change

Each journal is added to your batch as general journal lines, one per account, and the batch is then posted (journal lines API). Every line's Document No. is our marker (AH followed by 12 letters and digits) and its External Document No. is AhlanHamad's reference (for example PAY-KW-2026-10). If an attempt is cut off before posting, the next one removes our own unposted lines from the batch and adds them again; it looks for an already posted journal by its Document No. first (G/L entries API).
We never edit or delete a journal in Dynamics 365 Business Central. 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 Dynamics 365 Business Central 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 Dynamics 365 Business Central 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.

7. Check your first payroll in Business Central

In AhlanHamad, open the payroll run. The Dynamics 365 Business Central journals card lists each journal (Payroll accrual, Salary payment, …) with its status. Posted means Business Central has it.
In Business Central, open General Ledger Entries and filter Document No. on the marker the run card shows (AH…), or External Document No. on the reference.
Check: the posting date (the last day of the payroll month for the accrual), one entry per mapped account, and totals that match the payroll run in AhlanHamad.
Check that your AhlanHamad batch is empty again: a posted batch keeps no lines.

Statuses on the run card: Queued and Sending (on its way), Waiting (another journal must reach Dynamics 365 Business Central first), Retrying (Dynamics 365 Business Central or the network was busy; we try again automatically), Posted, On hold (needs you; the reason is shown), Failed (Dynamics 365 Business Central refused it; the reason is shown), Not needed (nothing to send; the reason is shown).

8. Troubleshooting

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

When connecting (Connection tab)

What you see	What to do
Enter your Microsoft Entra tenant ID (a GUID) or primary domain (contoso.onmicrosoft.com).	Paste the Directory (tenant) ID from the app's Overview, or your `….onmicrosoft.com` domain.
Enter the Business Central environment name exactly as the admin center shows it (for example Production or Sandbox).	Copy the name from the Environments tab of the Business Central admin center.
Microsoft Entra refused the app credentials (…): …	The Client ID or Client Secret is wrong, the secret expired, or the tenant is not the app's. Check them in the Entra admin center and connect again.
Business Central refused the app (…). Check the environment name, and that the app is registered in Business Central (Microsoft Entra Applications) with permission to post journals.	The token was issued but Business Central said no. Check the environment name; that the app's card in Microsoft Entra Applications is Enabled and has permission sets; and that API.ReadWrite.All shows Granted in the Entra admin center.
Could not reach Business Central.	Microsoft didn't answer. Try again in a few minutes.

When loading your accounts (Field Mapping tab)

What you see	What to do
Business Central did not report the company's local currency. Set the LCY Code in General Ledger Setup, then load your accounts again.	In Business Central, open General Ledger Setup, fill in LCY Code, then click Reload accounts.
Your batch is not in the General journal batch list	The list shows the batches Business Central's API returns. Check the batch exists in this company, then click Reload accounts. If it still isn't there, tell us which journal template it is in.

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, choose the company and the General journal batch, save the mapping, then Retry. This also shows when the connection now reaches a different tenant or environment than the saved setup.
… 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 Business Central terms: an account with Direct Posting off, a heading or total, or a blocked account. Map those codes to a Posting account with Direct Posting on, 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 Dynamics 365 Business Central.
The connection needs to be renewed. Reconnect and try again.	Microsoft Entra stopped accepting the app: usually the client secret expired, or consent or the app was removed. Create a new secret, then on the Connection tab click Replace credentials, enter it and click Reconnect. Journals held for this reason are sent automatically once you reconnect.
Not connected, or posting is switched off.	Connect Dynamics 365 Business Central again on the Connection tab. Held journals are sent automatically once you reconnect. If Dynamics 365 Business Central 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 Dynamics 365 Business Central, in English, with Dynamics 365 Business Central's own words added after ours. Fix the cause in Dynamics 365 Business Central or in the mapping, then press Retry. A retry never creates a second journal.

What you see	What to do
Business Central rejected the journal (400). followed by Dynamics 365 Business Central's own message	Read Business Central's message after ours (it starts with its error code in brackets). Common ones: the posting date is outside the allowed posting dates for the app's user or in General Ledger Setup, or an account has Direct Posting off. Fix it, then Retry.
Business Central refused access (403). The connection may lack permission to post journals, or the organisation was disconnected — reconnect Business Central.	The app connects as itself, with no signed-in user. In Business Central, check its Microsoft Entra Applications card is Enabled and has the permission sets from section 3, and in the Microsoft Entra admin center that API.ReadWrite.All shows Granted for the app. Then Retry.
Business Central 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 Dynamics 365 Business Central. Click Reload accounts, fix the mapping, save, then Retry.
This run's payroll accrual journal did not reach Dynamics 365 Business Central. 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.	Dynamics 365 Business Central or the network kept failing. Check Dynamics 365 Business Central opens normally, then press Retry.
The Business Central journal batch has … line(s) that are not this payroll journal. Posting a batch posts every line in it, so payroll needs a batch of its own: empty this one or pick another on the Business Central page.	Someone else's lines are in your AhlanHamad batch. Move or delete them in General Journals, or create a new batch and choose it on the Field Mapping tab, then Retry.
Business Central refused the journal (409).	The batch was busy or not empty. Check the batch in General Journals, then Retry.

On the payroll run: Not needed

What you see	What it means
Reversed in Ahlan Hamad before it reached Dynamics 365 Business Central; the pair nets to zero.	Nothing to do: the journal and its reversal cancel out, so neither is sent to Dynamics 365 Business Central.
Reverses an entry that never reached Dynamics 365 Business Central, so there is nothing to reverse there.	Nothing to do.

Two accounting systems

If the Dynamics 365 Business Central 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 Dynamics 365 Business Central, disconnect the others so payroll costs aren't counted twice.

9. Disconnecting

In AhlanHamad, go to Integrations → Dynamics 365 Business Central → Connection and click Disconnect Business Central. AhlanHamad deletes the stored credentials.
AhlanHamad cannot withdraw anything at Microsoft for you. If you won't use the app again, set its State to Disabled in Microsoft Entra Applications, and delete its client secret (or the app registration) in the Microsoft Entra admin center.

Journals already in Dynamics 365 Business Central stay there. We never delete or change them.
While Dynamics 365 Business Central is disconnected, new payroll journals are not sent. The run card says “Dynamics 365 Business Central 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.

Microsoft sources used in this guide

Business Central: service-to-service authentication, the admin center, environments, general journals, General Ledger Setup (training module).
Business Central API v2.0: journals and the post action, journal lines, general ledger entries.
Microsoft Entra: register an application, add a client secret, grant admin consent, find your tenant ID.
Microsoft's menus change from time to time. If a name here doesn't match your screen, the linked page has Microsoft's current wording.

About AhlanHamad × Dynamics 365 Business Central· All integrations