1. Home
  2. Articles
  3. Fintech
  4. The Fintech API Playbook
Post image

The Fintech API Playbook

Ardi Coetzee
By Ardi Coetzee
34

Fintech products live or die on trust. Before you approve a payout, open an account, onboard a merchant, quote an exchange rate, or allow a high-value transaction, you need to know who is on the other side.

That does not mean every applicant should immediately enter a long, expensive verification flow.

A better approach is progressive due diligence: run fast, targeted checks early; identify obvious mismatches, fraud signals, sanctions concerns, and payment risks; then reserve deeper verification for applicants and transactions that genuinely warrant it.

Teruza’s API catalogue provides a practical set of building blocks for that approach. With one authentication model and standard HTTP endpoints, a fintech team can add identity checks, bank-account validation, business lookup, AML screening, pricing data, geolocation intelligence, holiday awareness, and SMS delivery directly into its product workflow.

Start with the cheapest, highest-signal checks

The objective is not to replace compliance processes with a few API calls. It is to make the process more selective.

A sensible onboarding flow might start with an ID number, phone number, IP address, and basic customer details. From there, you can validate the identity data, identify suspicious location signals, screen the person or business against AML data, and only then decide whether to request additional documents or perform a deeper review.

This supports a risk-based approach: apply proportionate controls, focus effort where the risk is higher, and do not treat every customer identically. Formal customer due diligence requirements still apply according to the jurisdictions, product, transaction type, and risk profile involved.

1. Bank Account Verification: Reduce payout and collection risk

For any product that pays customers, collects debit orders, settles merchant balances, or verifies beneficiaries, bank account validation should be a core control.

Endpoint: POST /api/v1/banking/bank_account_verification

This endpoint supports real-time verification for a range of South African banks. It accepts the bank name, branch code, account number, account type, ID number or company-registration reference, initials, and surname or company name.

Use it when:

  • Adding a withdrawal or payout account
  • Confirming a merchant settlement account
  • Validating a supplier or beneficiary before payment
  • Checking that account-holder details match the customer or business profile
  • Reducing misdirected payments caused by incorrect bank details

For an individual, match the verified account against the person’s identity record. For a business, use the company name and applicable registration information. Do not treat bank details as trusted merely because a user entered them.

2. ID Number Verification: Establish a reliable identity baseline

A South African ID number contains valuable identity information, but accepting a number without validation creates obvious exposure.

Endpoint: POST /api/v1/id_verification/said_verification

This endpoint verifies a 13-digit South African ID number and returns corresponding consumer details.

Use it early in the flow to:

  • Validate that the ID number is structurally and externally credible
  • Compare returned first names and surname against the submitted application
  • Detect obvious identity mismatches before requesting documents
  • Create a stronger identity record for later AML, bank-account, and transaction checks

This should be one of the first gates in a South African onboarding flow. A customer whose ID data does not match their application should not proceed straight to account activation or payment access.

3. CIPC Company Lookup: Verify the business before onboarding it

Business onboarding introduces a different set of risks: shell entities, incorrect registration details, false directors, misrepresented trading names, and payment accounts that do not belong to the applicant.

Teruza exposes two CIPC lookup endpoints:

  • POST /api/v1/companies/cipc_company_name_lookup
  • POST /api/v1/companies/cipc_company_reg_nr_lookup

These lookups retrieve South African company and commercial-principal information from CIPC data.

They are especially useful for:

  • Merchant onboarding
  • SME lending applications
  • Marketplace seller verification
  • Business expense and payment platforms
  • B2B credit applications
  • Supplier onboarding

A practical workflow is to look up the business by registration number, compare the returned entity information against the application, validate the settlement bank account, then screen the company and relevant principals for AML and adverse-media risk.

That creates a far stronger business onboarding process than relying on a company name entered into a form.

4. Currency APIs: Build pricing, quotes, and portfolio views

Currency data is foundational for cross-border payments, treasury tools, crypto dashboards, multi-currency wallets, and merchant pricing.

Teruza provides three relevant endpoints:

  • GET /api/v1/currencies/all
  • GET /api/v1/currencies/crypto
  • GET /api/v1/currencies/forex

The all-currencies endpoint returns both crypto and forex rates, while the other two provide focused data sets.

Use these endpoints to:

  • Display indicative FX rates in a wallet or remittance product
  • Calculate multi-currency balances
  • Price cross-border transfers
  • Show crypto asset values in portfolio views
  • Convert transaction values into a reporting or settlement currency
  • Monitor exchange-rate movement before presenting a customer quote

For quote-sensitive flows, store the rate used, timestamp it, set an expiry window, and make it clear whether the displayed figure is indicative or executable.

5. Geolocation: Add context to login and transaction risk

An IP address is not proof of a person’s identity. It is, however, a valuable risk signal.

Endpoint: POST /api/v1/geolocation/geolocate

The endpoint maps an IPv4 or IPv6 address to location data and returns additional IP intelligence, including indicators such as threat level, crawler status, and proxy status.

This can support:

  • Login risk scoring
  • Country mismatch detection
  • Proxy and automated-traffic detection
  • Transaction monitoring
  • Velocity and behavioural analysis
  • Fraud-rule triggers for account changes or withdrawals

For example, a new account created with South African identity data, a South African mobile number, and an IP location from another region is not automatically fraudulent. It is a signal worth combining with other signals: device history, failed OTP attempts, account-detail changes, transaction size, and AML results.

6. AML Search: Screen before exposure increases

Sanctions and watchlist screening should not be an afterthought. It should be integrated into onboarding and material-risk events.

Endpoint: GET /api/v1/kyc/aml/search

The AML Search endpoint screens sanctions and other watchlists. It accepts an applicant type of person or company, a full name, and a date of birth.

Use AML screening when:

  • Opening an account
  • Approving a merchant
  • Onboarding a business
  • Enabling withdrawals or high-value payments
  • Reviewing suspicious transactions
  • Re-screening customers periodically or after profile changes

A potential match is not a final decision. Names can collide, dates of birth can be incomplete, and results require a documented review process. The point of the API call is to surface the cases that should not move forward automatically.

7. Adverse Media Lookup: Find reputational and financial-crime signals

AML lists alone do not capture every meaningful risk signal.

Endpoint: GET /api/v1/kyc/adverseMedia/search

The Adverse Media Lookup searches global news sources using a person, entity, or keyword search.

This is useful for:

  • Merchant and business onboarding
  • Enhanced review of AML matches
  • High-value lending applications
  • High-risk customer segments
  • Periodic reviews of active customers
  • Investigations triggered by unusual activity

Adverse media should be treated as a review trigger, not an automated rejection rule. Search results need context, relevance assessment, and a clear audit trail.

8. Holidays: Make payment timing predictable

Payments do not move on every calendar day.

Endpoint: POST /api/v1/misc/holidays

The Holidays endpoint returns public holidays for a country and year using an ISO 3166-1 alpha-2 country code, such as US or ZA.

This is useful for:

  • Cross-border payment scheduling
  • Settlement-date estimates
  • Customer communication
  • Treasury operations
  • Batch-payment planning
  • Avoiding misleading “next business day” promises

For example, a US public holiday calendar can help a fintech product explain expected timing around US banking activity. Public holidays are not always identical to every bank’s or payment rail’s operating schedule, so use the data as a scheduling input rather than the only source of settlement logic.

9. SMS: Secure onboarding and transaction confirmation

SMS remains useful for phone verification, one-time passwords, withdrawal confirmation, transaction alerts, and account-recovery flows.

Endpoint: POST /api/v1/sms/send

The endpoint sends SMS messages to mobile numbers internationally and supports immediate or scheduled delivery.

For OTP workflows, the API should handle delivery, while your application controls the security model:

  • Generate a high-entropy code
  • Hash the code before storage
  • Set a short expiry
  • Limit verification attempts
  • Rate-limit resend requests
  • Invalidate the code after successful use
  • Require stronger verification for high-risk actions

SMS is useful, but it should not be the only control for high-value transfers or sensitive profile changes. Combine it with device intelligence, session controls, and risk-based step-up verification.

A practical progressive-diligence flow

  1. Capture identity details, phone number, company details where applicable, and IP address.
  2. Run ID verification and geolocation.
  3. Send an SMS OTP to confirm control of the mobile number.
  4. Run AML and adverse-media screening once the identity data is credible.
  5. For businesses, perform CIPC lookup and validate the business settlement account.
  6. Validate bank details before enabling withdrawals, payouts, or collections.
  7. Use forex, crypto, and holiday data to power transaction pricing, payment timing, and reporting.
  8. Escalate only suspicious, high-risk, or high-value cases into deeper verification and manual review.

The value is not in any single endpoint. It is in the sequence.

By combining low-cost identity, location, company, AML, media, banking, messaging, and market-data checks, fintech teams can reduce avoidable risk early, keep legitimate users moving, and reserve intensive review for the cases that actually require it.

Source note: Endpoint methods, parameters, availability, and pricing should be confirmed against the current Teruza API documentation before production rollout.