FNB Integration Channel Service Catalogue ZA

Summary

We should integrate the FNB Integration Channel Service Catalogue ZA (https://www.fnb.co.za/integration-channel/catalogue/serviceCatalogue-ZA/) into our project to support direct banking operations such as EFT payments, collections, mandates (DebiCheck), and transaction history retrieval. This will allow our SDK to provide businesses seamless access to FNB’s host-to-host and API-based services.

---

Why This Matters

• Direct bank integration: Provides first-class support for EFTs, mandates, and reconciliation directly with FNB.
• Improves developer experience: Our SDK abstracts away the complexity of FNB’s host-to-host and API formats.
• Business value:
  • Faster settlement, real-time status tracking, and automated reconciliation
  • Local currency and bank-grade compliance
  • Reduced integration costs for enterprises
• Extensible: Foundation for expanding to other FNB services (proof of payment, debit orders, etc.).

---

Acceptance Criteria

1. Dependency / Setup

   • Integrate an HTTP client to interact with available FNB APIs.
   • Support host-to-host (H2H) flows where APIs are not available.
   • Configure secure authentication (certificates, tokens, or OAuth as required).

2. Core Workflows

   • EFT Payments — create and track outgoing payments.
   • EFT Collections — initiate and track incoming debits.
   • DebiCheck Mandates — create, manage, and verify mandates.
   • Transaction History — query account transactions.
   • Proof of Payment — retrieve and validate PoP details.

3. Webhook / Callback Support

   • Handle asynchronous responses from FNB (e.g. payment confirmations, failures).
   • Verify authenticity of callbacks.
   • Update database / SDK state accordingly.

4. Testing

   • Mock FNB endpoints (using Go’s httptest or local fixtures).
   • Provide integration tests against a sandbox environment (if available).
   • Add unit tests for SDK functions (payments, collections, mandates).

5. Documentation

   • Update README with Getting Started instructions.
   • Provide code snippets for:
     • Sending an EFT payment
     • Retrieving a transaction history
     • Creating a DebiCheck mandate
   • Document authentication and required configs (sandbox vs. production).

6. Error Handling & Logging

   • Gracefully handle network failures, invalid responses, or H2H file errors.
   • Support retries, idempotency, and structured logging.
   • Ensure compliance with FNB’s security and rate limits.

---

Additional Notes

• Some services require Host-to-Host integrations rather than APIs — these should be abstracted behind SDK methods.
• Consider designing the SDK so additional banks can be supported in the same structure.
• Work closely with FNB’s documentation and business onboarding requirements.
• Use clean interfaces, e.g. sdk.FNB.Payments.Create(params) or sdk.FNB.Mandates.Verify(id)

---

Research or References

• FNB Integration Channel Service Catalogue ZA: https://www.fnb.co.za/integration-channel/catalogue/serviceCatalogue-ZA/
• FNB Integration Channel Overview: https://www.fnb.co.za/integration-channel/
• Go net/http & context for API requests
• Go httptest for mocking API calls in unit tests