External API
Foreign Passport Bank Validation
Foreign passport checks run in real time. A completed check returns HTTP 200 with the result. Jobs and signed webhooks apply only when the request falls back to asynchronous processing.
Asynchronous fallback
Validate a South African bank account held by a foreign passport holder. Send one API request. VerifyNow sends the completed result to your signed webhook.
Capitec Business API integration questions
1. What do completed and failed callbacks contain?
HTTP 202 confirms that the job was accepted. Store its jobId and use the existing status endpoint or signed webhook for the final outcome. Eligible checks can finish through real-time processing; batch checks can take several hours or wait for the next bank processing window. A supplier failure after acceptance appears in the job result and business_bank.verification.failed callback. Completed callbacks include verified or review results. Failed results include verification_failed or verification_timed_out. reportType remains foreign-bank for compatibility.
2. Which checks are returned?
The nine checks are accountFound, accountOpen, accountNumberLengthValid, accountTypeMatch, companyRegistrationMatch, initialsMatch, surnameMatch, acceptsDebits and acceptsCredits. Each is true, false or null. Null means unavailable or undetermined. accountNumberLengthValid is the legacy API name for whether the account has been open for at least three months; it measures account age. The field name is retained for compatibility. companyRegistrationMatch is the identifier match; surnameMatch is the company/account-holder name match. Failed results contain error details instead of checks.
3. Is review a final outcome?
The outcome values are verified, review and failed. Review is final and uses business_bank.verification.completed. Verified requires accountFound, accountOpen, accountTypeMatch, companyRegistrationMatch and surnameMatch to be true. A false or null value among those five produces review. An account-type mismatch requires review so the submitted type can be checked. An explicit No for acceptsCredits or acceptsDebits also requires review. Initials and the account-age field accountNumberLengthValid remain informational; an account being under three months old is not a mismatch in submitted details.
4. What does billing_pending mean?
The bank result has arrived and charging is outstanding. The saved result and callback are withheld until charging succeeds. The worker is scheduled every minute. Insufficient-credit retries are scheduled 15 minutes apart; billing exceptions retry after five minutes. There is no fixed maximum billing hold. Keep the required credits available until completion. The 48-hour bank-result timeout does not cap billing holds.
5. Can I submit trust and NPO identifiers?
companyRegistrationNumber accepts a JSON string without an identifier-format or field-specific length check. Existing CIPC formats and 13-digit SA IDs retain their normalisation and mapping. Other strings retain letters, slashes, hyphens, case and whitespace. Use the identifier recorded by the bank. String acceptance does not establish bank support or a bank match.
6. Can I submit a sole proprietor’s passport number?
Yes. Submit the sole proprietor’s passport number as a string in companyRegistrationNumber, with letters and separators intact. Use the passport number and account-holder name recorded by the bank. A match depends on those bank records.
7. How are names matched?
Submit the account-holder name recorded by the bank in companyName. The backend derives the supplier fields from this value and companyRegistrationNumber, including legal suffixes for supported company registrations and given-name/surname fields for supported personal IDs. The submitted details remain available in the dashboard. surnameMatch reports the company/account-holder name match; null means unavailable. initialsMatch can be null when no separate initials comparison is returned. A name mismatch produces a completed review result. Sandbox matches are synthetic.
8. Which account types are accepted?
bankAccountType accepts unknown, current, cheque, savings, transmission, bond and credit-card. Values are case-insensitive and surrounding whitespace is trimmed. Current and cheque map to the same account type.
9. What do consent and purpose mean?
Set consentConfirmed to true after obtaining the authorisation required for the check, and retain supporting evidence. The API records the confirmation and timestamp. Purpose describes your lawful business reason. Example: Verifying that the merchant owns the bank account Yoco pays their sales proceeds into, for scheduled and ad hoc payouts. This wording fits the field limit; the purpose field does not itself obtain consent.
10. How long is an Idempotency-Key remembered?
Production requires an Idempotency-Key; sandbox can generate one when omitted. This business-bank route stores the key against the account and job with no time-based expiry in the lookup. Reuse it only for the original request. An identical normalised payload resolves to the existing job; a changed payload returns 409. This is an exception to the general 72-hour retry guidance. Status reads show the saved job state.
11. What rate and concurrency limits apply?
Sandbox repeats from the same IP, endpoint and identifier have a two-second cooldown: HTTP 429 with Retry-After: 2. Production accepts concurrent submissions with a separate Idempotency-Key for each new verification. The bank verification service queues accepted batch jobs for processing; concurrent submission does not guarantee concurrent completion. The production handler defines no endpoint-specific rate or concurrency cap. Infrastructure and bank capacity still apply; confirm expected peak volumes before rollout.
12. Can callback IPs be allowlisted, and how are callbacks secured?
Fixed callback IPs are not configured. Delivery requires public HTTPS. HMAC-SHA256 signs the timestamp, a dot and the raw JSON body with your webhookSecret; the header is x-verifynow-signature with value v1=<hex digest>. The secret is never included in the callback. Verify the signature using a constant-time comparison, check x-verifynow-timestamp within five minutes of your clock, and deduplicate using the event id inside the verified body in durable storage. A strong random secret and these checks authenticate the payload, detect changes and prevent repeated processing. Return 2xx within 15 seconds. Delivery retries use delays of 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours.
13. Which sandbox failure scenarios are available?
A valid account number ending in 90 produces a completed review result with accountFound and accountOpen false. Ending in 91 returns HTTP 502 at submission, before creating a job or callback. Other valid account numbers use the passing fixture. Use the optional x-verifynow-sandbox-scenario header to select the additional fixtures in the Sandbox test scenarios section. Requests without the header retain the account-ending behaviour described here. Sandbox is synthetic and does not establish bank support for an identifier. Use https://www.verifynow.co.za/api/bank-verification/callback-check as a signed sandbox receiver; append ?simulate=unauthorized to exercise delivery failure.
14. Are API keys shared between sandbox and production?
Use the same x-api-key and set mode to sandbox or production. Sandbox uses synthetic results, zero credits and no bank enquiry.
15. What request-size and field limits apply?
The entire JSON request body is limited to 4.5 MB by the hosting platform; larger payloads receive HTTP 413. This does not establish bank identifier limits. See the field table below. String lengths use JavaScript UTF-16 code units. Names and purpose collapse repeated whitespace and are trimmed before length checks. URL and secret are trimmed. New identifier strings are preserved as supplied.
16. What does "Confirm bank details before retrying" mean, and how does it relate to CDV?
CDV means Check Digit Verification. It checks whether the account number passes the validation rules for the selected bank and branch. A CDV failure leaves account ownership, account-open status and name or identifier matches unconfirmed. For this business-bank endpoint, a CDV or bank-detail rejection, or a real-time response without usable verification fields, ends the check with "Confirm bank details before retrying. No credits charged." A missing result leaves its underlying cause unconfirmed. The service keeps the submitted bank and branch; the merchant must confirm the details before submitting a corrected request with a new Idempotency-Key. Read result.error.message through the existing job-status response or business_bank.verification.failed callback. An administrative recheck of a previously charged job can instead return "Confirm bank details before retrying. No additional credits charged." The original charge remains recorded in creditsUsed.
| Field | Accepted length / requirement |
|---|---|
| companyName | 2–160; control characters rejected |
| companyRegistrationNumber | Required JSON string; no field-specific format or length check |
| purpose | 3–160 |
| webhookUrl | Required public HTTPS URL; maximum 2,048 |
| webhookSecret | 32–256; use a cryptographically random secret |
Sandbox test scenarios
Send mode: "sandbox" and the optional x-verifynow-sandbox-scenario header on POST /api/external/business-bank-account-verification. Requests that omit the header keep their existing sandbox behaviour. The header selects the scenario; the example account numbers alone keep their existing results.
For the first six scenarios, every other check is true and the event is business_bank.verification.completed. Debit and credit acceptance do not determine the overall outcome. The timeout scenario sends business_bank.verification.failed with error.code verification_timed_out and no checks. It uses the next webhook delivery cycle without waiting 48 hours. All scenarios cost zero credits.
Use a fresh Idempotency-Key when changing scenarios. Repeating the same request and key returns the existing job; changing the scenario with the same key returns HTTP 409. Existing validation and the two-second sandbox cooldown apply. Account numbers ending 91 retain the HTTP 502 submission error, including when the header is present. A supported scenario overrides the review fixture for ending 90. An empty or unsupported scenario header in sandbox returns HTTP 400.
To switch to production, set mode: "production", remove the scenario header and submit real account details with a fresh Idempotency-Key. Production ignores the scenario header, including unsupported values, and uses the existing live verification and billing flow.
| Header value | Example account | Result | Outcome |
|---|---|---|---|
| company_registration_mismatch | 123456792 | companyRegistrationMatch: false | review |
| name_mismatch | 123456793 | surnameMatch: false | review |
| closed_account | 123456794 | accountOpen: false; accountFound: true | review |
| debits_rejected | 123456795 | acceptsDebits: false | verified |
| credits_rejected | 123456796 | acceptsCredits: false | verified |
| name_unavailable | 123456797 | surnameMatch: null | review |
| verification_timed_out | 123456798 | error.code: verification_timed_out | failed |
curl -X POST https://www.verifynow.co.za/api/external/business-bank-account-verification \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sandbox-company-mismatch-001" \
-H "x-verifynow-sandbox-scenario: company_registration_mismatch" \
-d '{
"companyName": "Example Business (Pty) Ltd",
"companyRegistrationNumber": "2020/123456/07",
"bankName": "Capitec Business",
"bankAccountNumber": "123456792",
"bankBranchCode": "450105",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Sandbox integration testing",
"webhookUrl": "https://YOUR_DOMAIN/webhooks/verifynow",
"webhookSecret": "REPLACE_WITH_A_RANDOM_SECRET_OF_AT_LEAST_32_CHARACTERS",
"mode": "sandbox"
}'Synthetic callback examples
The completed example is a sandbox fixture. The failed example illustrates a production failure; sandbox suffix 91 returns an HTTP error before job creation.
business_bank.verification.completed
{
"id": "evt_11111111111141118111111111111111",
"type": "business_bank.verification.completed",
"createdAt": "2026-10-26T10:00:00.000Z",
"data": {
"jobId": "11111111-1111-4111-8111-111111111111",
"status": "completed",
"mode": "sandbox",
"reportType": "foreign-bank",
"creditsUsed": 0,
"result": {
"outcome": "verified",
"checks": {
"accountFound": true,
"accountOpen": true,
"accountNumberLengthValid": true,
"accountTypeMatch": true,
"companyRegistrationMatch": true,
"initialsMatch": true,
"surnameMatch": true,
"acceptsDebits": true,
"acceptsCredits": true
},
"bank": {
"name": "CAPITEC BUSINESS",
"accountNumberLast4": "6789"
}
}
}
}business_bank.verification.failed
{
"id": "evt_22222222222242228222222222222222",
"type": "business_bank.verification.failed",
"createdAt": "2026-10-26T10:00:00.000Z",
"data": {
"jobId": "22222222-2222-4222-8222-222222222222",
"status": "failed",
"mode": "production",
"reportType": "foreign-bank",
"creditsUsed": 0,
"result": {
"outcome": "failed",
"error": {
"code": "verification_failed",
"message": "The bank verification could not be completed"
},
"bank": {
"name": "CAPITEC BUSINESS",
"accountNumberLast4": "6789"
}
}
}
}Endpoint
POST /foreign-bank-account-verificationAuthentication
Send your external API key in x-api-key.
Production Price
6 credits after a usable result completes.
Standard retail price includes VAT.
Delivery
Real-time JSON result in the same response (HTTP 200) when the check completes immediately.
Asynchronous JSON webhook with an HMAC-SHA256 signature.
The webhook is only used for asynchronous fallback when you supply webhook details.
Real-time response
On HTTP 200, use the result in the response. No job is created and no webhook is sent. A review outcome is a completed check and does not start another verification. A null check means the bank did not return that field.
{
"success": true,
"requestId": "8ae57bb5-a015-49a4-ac89-1e25149ed907",
"status": "completed",
"processingMode": "realtime",
"mode": "production",
"reportType": "foreign-bank",
"creditsUsed": 6,
"result": {
"outcome": "verified",
"checks": {
"accountFound": true,
"accountOpen": true,
"accountNumberLengthValid": null,
"accountTypeMatch": true,
"passportNumberMatch": true,
"initialsMatch": true,
"surnameMatch": true,
"acceptsDebits": true,
"acceptsCredits": true
},
"bank": {"name": "FNB", "accountNumberLast4": "7890"},
"passportCountry": "ZW"
}
}Webhook URL and secret are optional for real-time requests. Include both to enable asynchronous fallback. If fallback is needed without them, the API returns HTTP 503 with code ASYNC_FALLBACK_REQUIRES_WEBHOOK and charges zero credits. Use a new Idempotency-Key when changing request fields.
Sandbox requests without webhook fields simulate the real-time response. Sandbox requests with both fields exercise the asynchronous fallback and callback flow below.
Create Your Webhook
A webhook is an HTTPS page in your backend that receives a POST when the bank result is ready. It can live at a path such as https://api.yourcompany.com/webhooks/verifynow.
1. Add the URL
Create a POST route on your backend. Choose Node.js, Python, or PHP from the working examples below.
2. Create a secret
Generate a random secret and save it as VERIFYNOW_WEBHOOK_SECRET on your server.
3. Deploy with HTTPS
Use the public HTTPS address from your hosting provider. VerifyNow validates the address before accepting the job.
4. Verify the signature
Build the HMAC from the timestamp and exact raw body. Compare it with x-verifynow-signature.
5. Save each event once
Store x-verifynow-event-id in your database. Repeated delivery of that ID returns HTTP 200.
6. Run a sandbox job
Sandbox sends a mock result and uses zero credits. Move to production after the callback appears in your logs.
First webhook test without a backend
Open Webhook.site and copy its unique HTTPS URL into webhookUrl. Run the sandbox request and watch the mock callback arrive. Use your own signed endpoint for production customer data.
Generate the secret
openssl rand -hex 32Put the output in your server environment as VERIFYNOW_WEBHOOK_SECRET. Send the same value as webhookSecret in the API request.
With Node.js installed, this command creates the same kind of secret:
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"Signed headers
x-verifynow-event-idStable ID for duplicate handlingx-verifynow-timestampUnix timestamp in secondsx-verifynow-signaturev1=<hex HMAC-SHA256>Signed text: timestamp + "." + rawBody. Accept a timestamp within five minutes of your server clock.
Webhook Code
The signature uses the raw request bytes. Place the webhook route before a global JSON body parser in Node.js.
Node.js and Express
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const secret = process.env.VERIFYNOW_WEBHOOK_SECRET;
const seenEvents = new Set();
app.post(
'/webhooks/verifynow',
express.raw({ type: 'application/json' }),
(req, res) => {
const rawBody = req.body.toString('utf8');
const timestamp = req.header('x-verifynow-timestamp') || '';
const received = req.header('x-verifynow-signature') || '';
const eventId = req.header('x-verifynow-event-id') || '';
const expected =
'v1=' +
crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + rawBody)
.digest('hex');
const validLength = expected.length === received.length;
const validSignature =
validLength &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!validSignature || !fresh) return res.sendStatus(401);
if (seenEvents.has(eventId)) return res.sendStatus(200);
seenEvents.add(eventId);
const event = JSON.parse(rawBody);
console.log(event.type, event.data.jobId, event.data.result);
return res.sendStatus(200);
},
);
app.use(express.json());
app.listen(3000);Python and Flask
import hashlib
import hmac
import os
import time
from flask import Flask, request
app = Flask(__name__)
secret = os.environ["VERIFYNOW_WEBHOOK_SECRET"].encode()
seen_events = set()
@app.post("/webhooks/verifynow")
def verifynow_webhook():
raw_body = request.get_data()
timestamp = request.headers.get("x-verifynow-timestamp", "")
received = request.headers.get("x-verifynow-signature", "")
event_id = request.headers.get("x-verifynow-event-id", "")
signed = timestamp.encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret, signed, hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(timestamp or 0)) <= 300
if not hmac.compare_digest(expected, received) or not fresh:
return "invalid signature", 401
if event_id in seen_events:
return "ok", 200
seen_events.add(event_id)
event = request.get_json()
print(event["type"], event["data"]["jobId"])
return "ok", 200PHP
<?php
$secret = getenv('VERIFYNOW_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_VERIFYNOW_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_VERIFYNOW_SIGNATURE'] ?? '';
$eventId = $_SERVER['HTTP_X_VERIFYNOW_EVENT_ID'] ?? '';
$expected = 'v1=' . hash_hmac(
'sha256',
$timestamp . '.' . $rawBody,
$secret
);
$fresh = abs(time() - intval($timestamp)) <= 300;
if (!hash_equals($expected, $received) || !$fresh) {
http_response_code(401);
exit('invalid signature');
}
$event = json_decode($rawBody, true);
// Save $eventId in your database before processing the result.
// Return 200 when that event ID has already been saved.
http_response_code(200);
echo 'ok';Send the Validation
Start with mode: "sandbox". Production requests need a unique Idempotency-Key. A retry with the same key and request body returns the same job.
curl -X POST https://www.verifynow.co.za/api/external/foreign-bank-account-verification \
-H "x-api-key: $VERIFYNOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"firstName": "Tariro",
"surname": "Moyo",
"passportNumber": "AB123456",
"passportCountry": "ZW",
"bankName": "FNB",
"bankAccountNumber": "1234567890",
"bankBranchCode": "250655",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Customer bank account ownership check",
"webhookUrl": "https://api.example.com/webhooks/verifynow",
"webhookSecret": "$VERIFYNOW_WEBHOOK_SECRET",
"mode": "sandbox"
}'| Field | Value |
|---|---|
| passportCountry | Two-letter ISO country code, such as GB or ZW |
| bankAccountType | unknown, current, cheque, savings, transmission, bond, or credit-card |
| consentConfirmed | true after the passport holder has authorised the check |
| purpose | Your lawful business reason for the validation |
| webhookUrl | Public HTTPS endpoint that accepts POST requests |
| webhookSecret | Random secret with at least 32 characters |
Supported banks
ABSA, ACCESS BANK, AFRICAN BANK, ALBARAKA BANK, BANK ZERO, BIDVEST BANK, CAPITEC BANK, DISCOVERY BANK, ENL MUTUAL BANK, FINBOND MUTUAL BANK, FNB, GRINDROD BANK, INVESTEC, MERCANTILE BANK, NEDBANK, OLD MUTUAL, OM BANK, SASFIN BANK, STANDARD BANK, STANDARD CHARTERED, TYME BANK.
Accepted Response
HTTP 202 confirms that VerifyNow accepted the asynchronous job. Keep the jobId in your customer or payout record.
{
"success": true,
"jobId": "8ae57bb5-a015-49a4-ac89-1e25149ed907",
"status": "pending",
"mode": "sandbox",
"reportType": "foreign-bank",
"requiredCredits": 0,
"webhook": {
"delivery": "signed",
"eventTypes": [
"foreign_bank.verification.completed",
"foreign_bank.verification.failed"
]
}
}Completed Callback
The completed event contains match flags and masked bank data. A review outcome needs your normal manual review.
{
"id": "evt_8ae57bb5a01549a4ac891e25149ed907",
"type": "foreign_bank.verification.completed",
"createdAt": "2026-08-03T12:30:00.000Z",
"data": {
"jobId": "8ae57bb5-a015-49a4-ac89-1e25149ed907",
"status": "completed",
"mode": "production",
"reportType": "foreign-bank",
"creditsUsed": 6,
"result": {
"outcome": "verified",
"checks": {
"accountFound": true,
"accountOpen": true,
"accountNumberLengthValid": true,
"accountTypeMatch": true,
"passportNumberMatch": true,
"initialsMatch": true,
"surnameMatch": true,
"acceptsDebits": true,
"acceptsCredits": true
},
"bank": {
"name": "FNB",
"accountNumberLast4": "7890"
},
"passportCountry": "ZW"
}
}
}Processing Time
Real-time results return in the HTTP response. The queue times and webhook steps below apply to the asynchronous fallback only.
When processing starts
This dedicated route remains separate from standard real-time bank-account verification. HTTP 202 confirms that the job entered the processing queue. Store the job ID and your Idempotency-Key, then use the signed callback as the final result.
Observed test
A completed Capitec Business batch check took about 10 hours. This observed result is an example, not a turnaround guarantee.
Bank processing window
Capitec Business and other batch bank checks can take several hours. Requests submitted after the bank’s processing cut-off may wait until the next available processing window.
Terminal status
VerifyNow waits up to 48 hours for a final bank result. It then sends a signed failed event with error.code: "verification_timed_out".
Delivery Rules
HTTP response
Return any 2xx response within 15 seconds. After the first failed delivery, VerifyNow retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, and 24 hours.
Duplicate events
The same event ID can arrive again after a timeout. Save the ID before you update a payout or customer record.
Credits
Keep 6 credits available while a production job is processing. Billing occurs once a usable result is ready.
Support reference
Share the VerifyNow jobId in support requests. Keep passport numbers and full bank account numbers out of tickets.
See the main API reference for authentication, credits, errors, and general idempotency rules.
Job status and webhook recovery
This section applies to HTTP 202 asynchronous fallback jobs. Real-time responses have a requestId and a result, without a jobId or webhook delivery.
Retrieve a saved result with GET /api/external/foreign-bank-account-verification/jobs/{jobId} or GET /api/external/business-bank-account-verification/jobs/{jobId}. Use the same account’s x-api-key. Status reads use zero credits and never start a bank enquiry. A production result remains withheld while billing is pending.
If delivery fails, POST an empty JSON object to the job URL followed by /retry-webhook. To fix the destination or signing key, provide webhookUrl and webhookSecret together. HTTPS safety checks still apply. This retries delivery of the saved result without another verification or charge. The event ID remains stable so receivers can deduplicate deliveries.
Existing submission responses keep their HTTP 202 acknowledgement format. Repeating the original request with the same Idempotency-Key can requeue an exhausted callback for a completed job. Use the status endpoint for the current verification and delivery state. Fix HTTP 401 at the receiving webhook or update its URL and secret before retrying.
The authenticated dashboard report includes the submitted identity and account details for new checks. These details are stored encrypted in Redis for seven days, then expire. Saved check outcomes and audit metadata follow the applicable account retention policy.
Dashboard production checks send the requesting user a report-ready email linking to their authenticated results. Download the authenticated PDF within seven days to keep the submitted details. Reports show who requested the check, job status, start and completion times, elapsed run time and individual match flags. The API playground also provides saved-status and webhook-retry actions for both services; these use the original job’s mode.
Sandbox callback check
For sandbox integration tests, webhookUrl can be https://www.verifynow.co.za/api/bank-verification/callback-check with a signing secret of 32–256 characters. The receiver validates the job’s signature and acknowledges the callback. Add ?simulate=unauthorized to test an HTTP 401 receiver, then retry using the plain callback URL. No bank is contacted in sandbox and no credits are charged.
Dashboard users can open the specialist bank-check screen from Bank Account Verification. Foreign passport and Capitec Business checks appear in its authenticated status list, with a sandbox option and results shown when ready.