FNB Payment API Integration

Use this guide to configure, test, and verify direct payment submission from Business Central to FNB.

Outcome

After this guide:

1. Payment Journal exports for the configured bank account are sent to FNB API (not to file).
2. Each submitted batch appears in Payment Export Logs.
3. Status updates are retrieved successfully.
4. Approved payments can be posted confidently.

FNB API Onboarding

Complete FNB's onboarding process before configuring anything in Business Central. It is run by FNB and is how you obtain the Client ID and Client Secret required in Step 2.

1. Request API access

1. Contact your FNB Banker, or the Online Banking Enterprise (OBE) Helpdesk on 087 575 00 00, and ask for an Opportunity to be logged for provisioning of the FNB Payments API.
2. FNB allocates the Opportunity to a Platform Specialist (PS).
3. The PS contacts you to discuss your requirements and onboarding needs.

2. Confirm Online Banking Enterprise enrolment

1. The PS confirms whether you are enrolled on Online Banking Enterprise (OBE). The API can only be used by clients registered on OBE.
2. If you are not enrolled, the PS arranges OBE onboarding first.

3. Review API pricing

1. Discuss API-related fees with your Banker, or review your FNB Pricing Guide.
2. Confirm that you understand and accept any applicable fees.

4. Implementation Manager assignment

1. The PS requests an Implementation Manager (IM) to be assigned to your Opportunity.

5. Integration channel consultation

1. FNB schedules an Integration Channel meeting with you.
2. Your requirements are discussed and the appropriate API solutions are identified and provisioned. For this integration, request the Payments API.

6. Generate API credentials

1. During the provisioning session you generate your Client ID and Client Secret.
2. Store both values securely. You need them to set up the connection in Step 2, and Linc cannot retrieve or reset them for you.

7. Connectivity setup with Linc

1. Contact Linc for integration and connectivity support.
2. Linc assists you with API connectivity setup in Business Central, following the steps in this guide.

Before You Start

1. Confirm you have an active Premium subscription for this app.
2. Confirm you have FNB API credentials for the correct environment: Client ID, Client Secret, and gateway base URL. See FNB API Onboarding above if you do not yet have them.
3. Confirm you can edit Bank Integration Setup and Bank Export/Import Setup.
4. Confirm you have at least one test vendor with valid bank account and branch details.

Step 1: Verify Premium Subscription

1. Open Bank Integration Setup.
2. Open the FNB section.
3. Confirm FNB credential fields are editable.

Pass criteria:

1. FNB fields are editable.
2. No subscription warning blocks setup.

Step 2: Configure FNB Credentials

1. Open Bank Integration Setup.
2. In the FNB section, enter: FNB Client ID, FNB Client Secret, and FNB API Base URL. These credentials are issued by FNB, not by Linc, through the process in FNB API Onboarding. Make sure they were issued for the environment you are configuring. Linc cannot create, reset, or look up these values.
3. Enter the base URL without a trailing slash.
4. Save the page.

Environment base URLs:

Environment	Base URL
Integration	https://api.i.fnb.co.za/apigateway
Pre-production	https://api.p.fnb.co.za/apigateway
Production	https://api.fnb.co.za/apigateway

Pass criteria:

1. All three values are saved.
2. URL exactly matches the environment your credentials were issued for.

Step 3: Configure Export Format for API

1. Open Bank Export/Import Setup.
2. Open the payment export format record used for FNB.
3. Confirm Processing Codeunit is EFTExportFNB_Bank_LINC (Object ID 71113472).
4. Set Bank Export/Import file type to API.
5. Save.

Important:

1. API file type is only valid for the FNB export setup.
2. EFTExportFNB_Bank_LINC is the only processing codeunit that handles the API file type. Any other export codeunit will ignore the setting and continue producing a file.
3. If this step fails, resolve subscription or codeunit mismatch first.

Pass criteria:

1. File type is API on the FNB export format record.

Step 4: Link the Bank Account to the API Export Format

1. Open Bank Account Card for the bank account that will be debited.
2. Set Payment Export Format to the FNB setup record from Step 3.
3. Verify Bank Account No. matches the account registered at FNB.
4. Save.

Pass criteria:

1. Bank account points to the API-enabled FNB export format.
2. Bank account number is correct for the FNB profile.

Step 5: Validate Recipient Master Data

1. Open each Vendor Bank Account used for payments.
2. Confirm Bank Account No. is populated.
3. Confirm Bank Branch No. is populated.
4. Confirm the vendor Preferred Bank Account Code points to the correct vendor bank account.
5. If using Employee or Bank Account payment lines, confirm recipient bank details are complete there as well.

Pass criteria:

1. All intended recipients have complete bank details.

Step 6: Configure Automatic Status Refresh (Recommended)

Option A, filtered updates:

1. Create a Job Queue Entry for report PmtExportStatusUpd_BANK_LINC (Object ID 71113471).
2. Set report filters if you want specific template or batch scope.
3. Set recurrence and enable the job.

Option B, global updates:

1. Create a Job Queue Entry for codeunit PaymentAPIMgt_BANK_LINC (Object ID 71113481).
2. Set recurrence and enable the job.

Pass criteria:

1. Job queue entry is enabled.
2. Next run date and time are populated.

Step 7: Run a Controlled End-to-End Test

1. Create a Payment Journal test batch with one small-value line.
2. Use a recipient with confirmed valid bank details.
3. Ensure all lines use the same balancing bank account.
4. Ensure Account Type values are supported for API export.
5. Run Export.

Expected result:

1. Success message confirms the batch was sent.
2. A Payment Export Log entry is created.
3. Journal line Payment Export Status moves to Submitted.

If export fails:

1. Fix all listed validation issues.
2. Re-export the batch.

Step 8: Verify Bank Response and Final Status

1. Open Payment Export Logs from the Payment Journal.
2. Open the run created by the test.
3. Use Update Status.
4. Repeat after the bank processing window if still waiting.

Expected progression:

1. Submitted while awaiting final bank outcome.
2. Approved when paid.
3. Rejected or Error if refused or failed.

While the bank has no report yet:

1. The status stays Submitted and Status Reason notes the attempt. That message means the payment has not been approved or rejected on FNB's side yet.
2. Last Status Check updates on every attempt, so you can confirm the check actually ran.
3. Keep using Update Status periodically, or let the job queue from Step 6 do it.

Pass criteria:

1. Status retrieval succeeds without authentication errors.
2. Final status is received and recorded on run and lines.

Step 9: Handle Failures Correctly

1. For Rejected or Error lines, correct master data or journal data.
2. Use Resubmit when appropriate.
3. If a line changed after failure, export again from Payment Journal instead of resubmitting old run data.

Pass criteria:

1. Failed items can be resent through normal process.

Step 10: Move to Production

1. Repeat Step 2 using production credentials and production base URL when go-live is approved.
2. Repeat Step 7 with a controlled live smoke test.
3. Confirm job queue is active in production company.

Pass criteria:

1. Production test batch reaches Submitted and then Approved.

Completion Checklist

The setup is complete when all checks below are true:

1. FNB credentials are saved and match the active environment.
2. FNB export format is configured with API file type.
3. Bank account is linked to that export format.
4. Recipient master data is complete.
5. Test export creates a run in Payment Export Logs.
6. Update Status returns results successfully.
7. At least one test payment reaches Approved.

Payment Status Reference

The same status values appear on an individual payment and on the run that contains it, but they do not mean the same thing. A run's status is worked out from its payments.

On an individual payment

Status	Meaning
Pending	Recorded in the log but not yet sent. If the run failed to send, its payments stay Pending: nothing reached the bank.
Submitted	Accepted by the bank, final outcome still to come. Also used when the bank returns a status code the app does not recognise, in which case the raw code is shown in Bank Status Code and called out in Status Reason.
Approved	Paid by the bank.
Rejected	Refused by the bank.
Error	The payment could not be sent, or the bank did not accept the run it was in.
Amended	The payment was Rejected or Error, and a payment-relevant field on the journal line has changed since it was sent (amount, account type or number, recipient bank account, currency, message to recipient, or balancing account). The log no longer describes what should be paid, so this payment is excluded from Resubmit and must be sent from the Payment Journal.

On a run

Status	Meaning
Pending	The run was created but has not been sent. Transient: it becomes Submitted or Error as soon as the send completes.
Submitted	At least one payment is still Pending or Submitted.
Approved	Every payment in the run was paid.
Rejected	Every payment has settled and at least one was not paid. A run showing Rejected may still be partly paid.
Error	The run itself failed to send, or the bank refused the submission. Its payments stay Pending.

Important:

1. A run showing Rejected is not proof that nothing was paid. Compare Approved Lines with No. of Transactions, and check the individual payments, before correcting or re-sending anything.
2. The bank only produces a report once a payment is final, so Update Status leaves the status unchanged and notes the attempt in Status Reason. That message means the payment has not been approved or rejected on FNB's side yet. It is not a failure.
3. Update Status cannot be used on a run with status Error, because no instruction ID was ever returned for it. Use Resubmit instead.
4. Only Rejected and Error payments are eligible for Resubmit. Approved payments are never sent again, and Amended payments must go through the Payment Journal.