KYC Integration Inside NetSuite: A South African Guide

Understanding FICA and KYC Requirements in South Africa

The Financial Intelligence Centre Act (Act 38 of 2001) requires "accountable institutions" — including banks, financial service providers, estate agents, and certain businesses — to verify the identity of their clients and maintain records of transactions. The key requirements include:

• Client identification — verify the identity of individuals using an official ID document (South African ID, passport, or permit).
• Verification of identity — confirm that the person is who they claim to be, typically through biometric or database checks against the Department of Home Affairs (DHA).
• Ongoing due diligence — monitor client transactions for suspicious activity and report to the Financial Intelligence Centre (FIC).
• Record keeping — maintain KYC records for at least five years after the business relationship ends.

Non-compliance carries significant penalties. The FIC can impose administrative sanctions, and in serious cases, directors can face criminal prosecution. This is not a checkbox exercise — it requires robust, auditable processes.

Why Integrate KYC Directly into NetSuite?

Many businesses handle KYC as a separate, manual process — printing forms, copying ID documents, filing paperwork. This creates several problems:

• Delayed onboarding — manual verification can take days, frustrating customers and slowing revenue.
• Human error — manual data entry leads to mistakes that can cause compliance failures.
• Audit risk — paper-based records are hard to search, track, and present during audits.
• Disconnected data — KYC status is not linked to customer records in your ERP, requiring staff to check multiple systems.

Integrating KYC into NetSuite means verification happens inside the same system where you manage customers, transactions, and reporting. The customer record in NetSuite becomes the single source of truth for compliance status.

Identity Verification Providers for the South African Market

Several API-based services can verify South African IDs against the Department of Home Affairs database and perform additional checks. The providers ULB Media has successfully integrated with NetSuite include:

XDS (Xpert Decision Systems)

One of South Africa's leading credit bureaus, XDS offers identity verification, credit checks, and fraud detection APIs. Their ID verification service checks against the DHA population register and returns match results for name, surname, date of birth, and ID status (alive, deceased, or invalid).

Onfido

A global identity verification platform that supports South African ID documents. Onfido uses AI-powered document verification and biometric checks (selfie matching). Their API is well-documented and works well for businesses that also operate internationally.

Iidentifii

A South African-built platform specialising in biometric verification. Iidentifii integrates with the DHA and offers liveness detection (confirming a real person, not a photo). They are popular with South African financial institutions.

Bankserv Africa (Home Affairs Verification)

Bankserv provides direct access to the DHA verification system, commonly used by banks. Access typically requires being an accountable institution or working through a registered intermediary.

Technical Architecture: How the Integration Works

The integration follows a straightforward pattern:

1. A user creates or updates a customer record in NetSuite and enters the client's ID number.
2. A SuiteScript (User Event Script or Client Script) triggers the verification workflow.
3. A SuiteScript RESTlet or Suitelet calls the identity verification provider's API with the ID number and name.
4. The API response (verified, not verified, or requires manual review) is written back to custom fields on the customer record.
5. A workflow or saved search prevents transactions with unverified customers (if business rules require it).

Custom Fields on the Customer Record

You will need to create several custom fields on the Customer record type in NetSuite:

• custentity_kyc_status — List/Record field (Pending, Verified, Failed, Manual Review).
• custentity_id_number — Free-Form Text for the South African ID number.
• custentity_kyc_verified_date — Date field for when verification was completed.
• custentity_kyc_reference — Free-Form Text for the verification provider's reference ID.
• custentity_kyc_response — Long Text for storing the raw API response (for audit purposes).

SuiteScript Implementation Approach

Use a User Event Script (beforeSubmit or afterSubmit) on the Customer record to trigger verification automatically when an ID number is entered. The script should:

• Check if the ID number field has changed (to avoid redundant API calls).
• Validate the ID number format (South African IDs follow a specific 13-digit structure with a checksum).
• Call the verification API using N/https module.
• Parse the response and update the KYC status fields.
• Log the result for audit trail purposes.

For high-volume scenarios, consider using a Map/Reduce Script to process verification in batches, or a Scheduled Script that runs nightly to re-verify records approaching their expiry period.

South African ID Number Validation

Before calling an external API, validate the ID number format locally. A South African ID number is 13 digits with the following structure:

• Digits 1–6: Date of birth (YYMMDD).
• Digits 7–10: Gender indicator (0000–4999 = female, 5000–9999 = male).
• Digit 11: Citizenship (0 = SA citizen, 1 = permanent resident).
• Digit 12: Usually 8 (legacy digit).
• Digit 13: Luhn checksum digit.

Implementing the Luhn algorithm check in your SuiteScript catches invalid IDs before they reach the API, saving you API call costs and providing instant feedback to the user entering data.

Workflow Enforcement: Blocking Transactions for Unverified Customers

Once KYC status is tracked on the customer record, you can enforce compliance rules using NetSuite's native workflow engine or SuiteScript:

• Create a saved search that identifies customers with a "Pending" or "Failed" KYC status.
• Use a User Event Script on Sales Orders or Invoices to check the customer's KYC status before allowing the transaction to be saved.
• Display a warning or block the transaction entirely, depending on your business requirements.
• Send automated email notifications to compliance officers when manual review is required.

Audit Trail and Record Keeping

FICA requires that you maintain verification records for at least five years. NetSuite's system notes automatically log field changes, providing a built-in audit trail. For additional robustness:

• Store the full API response in a custom field or a related custom record.
• Log verification attempts (including failures) in a custom record type linked to the customer.
• Create a dashboard (saved search + portlet) for compliance officers to monitor KYC status across all customers.

ULB Media has built KYC compliance modules for several South African businesses running NetSuite. The key to a successful implementation is understanding both the regulatory requirements and the technical capabilities of the NetSuite platform — and bridging the gap between the two.

Choosing the Right Implementation Partner

KYC integration in NetSuite sits at the intersection of regulatory compliance, ERP customisation, and third-party API integration. This is not a standard NetSuite configuration task — it requires SuiteScript development expertise, understanding of South African compliance requirements, and experience working with identity verification providers.

Look for a partner who has done this before in the South African context, can provide references, and understands both the technical and regulatory sides. The cost of getting compliance wrong — both in penalties and reputational damage — far exceeds the cost of doing it right.