1. How the integration works

1. Obtain a test key and keep it in server-side secret storage.
2. Call application_types.php to discover the current fields and evidence requirements.
3. Submit one case to submit.php using multipart/form-data.
4. Save both your external_client_id and the returned FICA sure case_id.
5. Wait for the signed completion webhook, or poll status.php.
6. Read the final stable contract from v1/result.php.

The submit request is asynchronous. A successful HTTP 202 means the case was accepted and queued. It does not mean the verification has finished.

Small glossary

2. Quick start

What you need

• The public API base URL, normally https://api.ficasure.com/api/.
• An active FICA sure organisation.
• Test credits and a test API key while developing.
• A server-side application capable of HTTPS and multipart file uploads.
• A public HTTPS webhook URL if completed results must be pushed automatically.

Three-request connection test

Replace YOUR_CLIENT_KEY and run these requests in order. Receiving JSON from all three confirms the URL, key, environment and result access are working.

# 1. Confirm the key and balance
curl "https://api.ficasure.com/api/account.php" 
  -H "X-API-Key: YOUR_CLIENT_KEY" 
  -H "Accept: application/json"

# 2. Load the current application requirements
curl "https://api.ficasure.com/api/application_types.php" 
  -H "X-API-Key: YOUR_CLIENT_KEY" 
  -H "Accept: application/json"

# 3. After submitting a case, retrieve its status
curl "https://api.ficasure.com/api/status.php?case_id=123" 
  -H "X-API-Key: YOUR_CLIENT_KEY" 
  -H "Accept: application/json"

3. Test the integration with Postman

The supplied collection contains registration, key management, account, requirements, submission, status and result requests. It automatically saves a returned case_id after a successful submission.

1. Open Postman and choose Import.
2. Import FICA-sure.postman_collection.json.
3. Open the collection’s Variables tab.
4. Set base_url to https://api.ficasure.com/api without adding an endpoint filename.
5. Paste the test key into api_key. Never share an exported collection containing a real key.
6. Set environment to test. This variable is only used by key-management requests; the actual API key chooses the environment for authenticated calls.
7. Run Get account and credit balance, then Get application types and requirements.
8. Open Submit personal verification. In Body → form-data, replace the sample values. Enable each required file row and select a local file.
9. Give every intended case a new external_client_id.
10. Send the request. HTTP 202 is the normal queued response and the collection saves its case_id.
11. Run Get status by case ID until it is no longer queued/running, then run Get stable v1 result by case ID.

Several files in Postman

Duplicate the form-data row and keep the key exactly the same. Three address files must all use proof_of_address[]. Do not rename them to proof_of_address_1 or document2.

Common Postman mistake

Do not manually add Content-Type: multipart/form-data. Postman creates the required multipart boundary when Body is set to form-data. Add only X-API-Key and Accept: application/json.

4. Organisations, keys and environments

Cases, credits, keys and webhook settings are organisation-scoped. A customer key cannot retrieve another organisation’s case. An unauthorised lookup returns 404 Not found instead of confirming whether that case exists.

Do not send an environment field with a verification. FICA sure reads the environment from the key. Changing a form label to “live” while still sending a test key does not create a live case.

Recommended key setup

1. Sign in to FICA sure.
2. Open API Integrations.
3. Under Integration Access, enter the account password.
4. Create the test or live key.
5. Copy it immediately into server-side secret storage. It cannot be displayed again.

Alternative: register and manage keys by API

POST /api/register.php
Content-Type: application/json

{
  "organization_name": "Client X",
  "full_name": "Jane Doe",
  "email": "jane@example.com",
  "mobile": "+27110000000",
  "password": "at-least-10-characters"
}

Registration returns HTTP 201 with status pending. An administrator must activate the organisation and allocate credits before a key can be issued.

POST /api/credentials.php
Content-Type: application/json

{
  "email": "jane@example.com",
  "password": "CLIENT_PASSWORD",
  "environment": "test",
  "action": "issue"
}

FICA_SURE_API_BASE_URL=https://api.ficasure.com/api/
FICA_SURE_API_KEY=the_key_returned_once_by_fica_sure
FICA_SURE_WEBHOOK_SECRET=the_webhook_secret_returned_once

5. Endpoint reference

X-API-Key: YOUR_CLIENT_KEY
Accept: application/json

6. Application types, fields and evidence

Always load requirements first

GET /api/application_types.php
X-API-Key: YOUR_CLIENT_KEY

This response is authoritative. Administrators can change whether a supported field or document is required, so do not permanently hard-code one personal form.

Current application keys include personal, sole_proprietor, partnership, close_corporation, private_company, personal_liability_company, public_company, trust, estate, association_society_club_trade_union, npc_npo, and merchant_card_acceptance. Use the returned key, not its visible label.

Request metadata

Evidence rules

• Use multipart/form-data.
• File keys must exactly match a non-ignored document_modes key.
• Supported content types are JPEG, PNG, WebP and PDF. The server checks the real MIME type.
• The current limit is 15 MB per file. Hosting/proxy limits may be lower.
• Send up to three files per configured evidence type and up to five supporting_document[] files.
• Every repeated file is preserved and assessed separately.

Correct:

proof_of_address[] = address-letter.pdf
proof_of_address[] = municipal-account.jpg
proof_of_address[] = property-photo.webp

Incorrect:

proof_of_address_1
proofOfAddress
address_document
document2

7. Exact, Fuzzy 1 and Fuzzy 2 name checks

The website uses plain-language labels. API integrations select the same behaviour by sending name_matching_level with each case. The choice affects local FIC/UN name comparison and the configured PEP name search. It does not replace evidence, identity or date-of-birth checks.

# Exact / closest spelling only
-F "name_matching_level=0"

# Fuzzy 1 / allow small differences
-F "name_matching_level=1"

# Fuzzy 2 / search more broadly
-F "name_matching_level=2"

If omitted or invalid, the configured standard comparison is used. The final result confirms it in case.name_matching.level and case.name_matching.description.

8. Submit a verification

curl -X POST "${FICA_SURE_API_BASE_URL}submit.php" 
  -H "X-API-Key: ${FICA_SURE_API_KEY}" 
  -H "Accept: application/json" 
  -F "external_client_id=client-x-000123" 
  -F "source_app=client-x-website" 
  -F "application_type=personal" 
  -F "application_reference=ONBOARDING-000123" 
  -F "name_matching_level=1" 
  -F "full_name=Jane Doe" 
  -F "id_number=0000000000000" 
  -F "date_of_birth=1990-01-31" 
  -F "nationality=ZA" 
  -F "email=jane@example.com" 
  -F "mobile_number=+27110000000" 
  -F "terms_accepted=1" 
  -F "identity_document[]=@/secure/path/id.jpg" 
  -F "proof_of_address[]=@/secure/path/address.pdf" 
  -F "proof_of_address[]=@/secure/path/municipal-account.jpg" 
  -F "selfie[]=@/secure/path/selfie.jpg"

Replace every sample value and only send fields permitted by the selected application type.

Successful queued response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "success": true,
  "case_id": 123,
  "status": "queued",
  "environment": "test",
  "credits_reserved": 8
}

Save case_id, external_client_id, and environment immediately. If the connection breaks after sending, query by the same external ID before retrying so an accidental duplicate is not created.

Minimal PHP example

$post = [
  'external_client_id' => 'client-x-000123',
  'application_type' => 'personal',
  'name_matching_level' => '1',
  'full_name' => 'Jane Doe',
  'identity_document[0]' => new CURLFile('/secure/id.jpg', 'image/jpeg', 'id.jpg'),
];
$curl = curl_init(getenv('FICA_SURE_API_BASE_URL') . 'submit.php');
curl_setopt_array($curl, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 90,
  CURLOPT_HTTPHEADER => ['X-API-Key: '.getenv('FICA_SURE_API_KEY'), 'Accept: application/json'],
  CURLOPT_POSTFIELDS => $post,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($body === false) throw new RuntimeException(curl_error($curl));
$response = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 202) throw new RuntimeException($response['error'] ?? 'Submission failed');

9. Progress and stable results

GET /api/status.php?case_id=123
X-API-Key: YOUR_CLIENT_KEY

# Your identifier also works:
GET /api/status.php?external_client_id=client-x-000123

Stable v1 contract

GET /api/v1/result.php?case_id=123
X-API-Key: YOUR_CLIENT_KEY

# Or:
GET /api/v1/result.php?external_client_id=client-x-000123
X-API-Key: YOUR_CLIENT_KEY

Use this versioned endpoint in application code. It returns schema.name = cris_fica_result and schema.version = 1.0, with stable profile/document slots for every application type.

{
  "schema": {"name": "cris_fica_result", "version": "1.0"},
  "success": true,
  "case": {
    "case_id": 123,
    "external_client_id": "client-x-000123",
    "application_type": "personal",
    "name_matching": {"level": "1", "description": "Small spelling differences and common name variations"}
  },
  "processing": {"status": "completed", "stages": []},
  "decision": {"status": "approved", "identity_verified": true, "fica_complete": true, "application_access": "allow", "human_review_required": false},
  "completion": {},
  "profile": {"fields": []},
  "requirements": {"outstanding": [], "mismatches": [], "review_flags": []},
  "documents": [],
  "screening": {},
  "human_review": {},
  "customer_message": "",
  "usage": {},
  "billing": {}
}

Making an access decision

• HTTP 200 only means the result was retrieved.
• Inspect decision.status, decision.fica_complete, decision.application_access, and decision.human_review_required together.
• If human review is required or screening is not clear, never auto-approve.
• Show customer_message to the customer. Do not expose raw provider data or administrator diagnostics.

10. Receive completed results by webhook

A webhook means FICA sure calls your server when the result changes, so you do not need to poll continuously.

1. Create a public endpoint, for example https://client.example.com/webhooks/fica-sure.
2. Open API Integrations → Integration Access → Completion webhook.
3. Enter the HTTPS URL and enable delivery.
4. Confirm the account password and save.
5. Copy the signing secret immediately; it cannot be shown again.

Production endpoints must use HTTPS, resolve publicly and cannot point to private/reserved addresses or include embedded credentials. A hosted server cannot call localhost on your computer.

PHP receiver

$raw = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_FICA_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('FICA_SURE_WEBHOOK_SECRET'));
if (!hash_equals($expected, $received)) {
  http_response_code(401);
  exit;
}
$deliveryId = $_SERVER['HTTP_X_FICA_DELIVERY_ID'] ?? '';
// If this ID was processed before, return 204 without processing twice.
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
// Save or queue the result, then acknowledge quickly.
http_response_code(204);

Node.js/Express receiver

import crypto from 'node:crypto';
app.post('/webhooks/fica-sure', express.raw({type: 'application/json'}), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.FICA_SURE_WEBHOOK_SECRET).update(req.body).digest('hex');
  const received = req.get('X-FICA-Signature') || '';
  const valid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!valid) return res.sendStatus(401);
  const result = JSON.parse(req.body.toString('utf8'));
  // Store idempotently using X-FICA-Delivery-ID.
  return res.sendStatus(204);
});

Return 2xx quickly. FICA sure records the attempt and HTTP status. Keep status/result polling as recovery if your endpoint was unavailable during delivery.

11. Credits

GET /api/account.php
X-API-Key: YOUR_CLIENT_KEY

The key selects the test or live balance. Read credits.balance, credits.reserved, and credits.available. A case reserves an estimate when accepted; successful processing finalises it; technical failure releases/refunds it. Insufficient available credit rejects the submission.

12. Errors and troubleshooting

“FICA API unavailable”

1. Test from the client server, not only your browser.
2. Confirm the base URL ends in /api/.
3. Confirm the response is JSON, not HTML, a hosting login or firewall challenge.
4. Check DNS, TLS, outbound firewall, ModSecurity and PHP cURL.
5. Test account.php with the organisation key.

Test case not found with a live key

This is intentional. Use the same environment key that created the case.

Only one uploaded file appears

Use repeated canonical keys with brackets and confirm your library did not overwrite earlier map entries.

Live PEP screening error

Confirm the live organisation key created the case and live screening is enabled with a valid administrator-managed credential. A failed live call is not silently replaced with a local clear result.

Safe diagnostics

Record request time, endpoint, method, HTTP status, external_client_id, returned case_id, environment and a redacted response. Never record the key, password, webhook secret, evidence contents or unredacted personal data.

13. Production checklist

• Use the public HTTPS API URL.
• Keep secrets on the server only.
• Store separate test and live keys.
• Check account.php and returned environment.
• Load application_types.php.
• Honour required, optional, EDD-only and ignored modes.
• Use a unique external ID per intended case.
• Choose the name matching level.
• Send files as repeated canonical multipart keys.
• Save both identifiers.
• Treat 202 as queued, not approved.
• Use v1/result.php.
• Check decision, completion, access and human review together.
• Verify webhook signatures over the raw body.
• Deduplicate delivery IDs.
• Return 2xx quickly and keep polling as fallback.
• Handle ambiguous submissions without creating duplicates.
• Never expose provider identities, supplier responses, secrets or administrator diagnostics.