Compare a live selfie with the Home Affairs identity photo for stronger remote identity binding. Submit JPG/JPEG, PNG, WEBP or TIFF image data up to 5 MB per image.
Send a code when your user requests phone verification, save the verification ID in your application, then check the code they enter. Use the same send request key when retrying an interrupted response. A new code entry gets its own verify key.
OTP uses credential-bound environments. Omit mode and require a production verified result before continuing a live customer journey. Sandbox sends no SMS and uses the fixed code 123456. Use your existing approved API key and available credits.
// Run these requests from your server. Keep the API key private.
const base = 'https://www.verifynow.co.za/api/external';
async function otpRequest(path, body, idempotencyKey) {
const response = await fetch(base + path, {
method: 'POST',
headers: {'x-api-key': process.env.VERIFYNOW_API_KEY,
'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey},
body: JSON.stringify(body)
});
return {httpStatus: response.status, result: await response.json()};
}
// First request: persist sendKey and reuse it if the response is interrupted.
const sent = await otpRequest('/otp/send', {phoneNumber, reference}, sendKey);
// Store sent.result.verificationId in your application. Wait for the user to enter the code.
// A separate user action invokes verification with a fresh key for that code entry.
const checked = await otpRequest('/otp/verify', {
verificationId: savedVerificationId, code: enteredCode
}, verifyAttemptKey);
const phoneAccessConfirmed = checked.httpStatus === 200 &&
checked.result.verified === true && checked.result.environment === 'production';
VerifyNow does not accept an arbitrary array of checks in one public API request. Use a supported bundle where one exists. For a custom combination, expose one endpoint from your server and let that endpoint coordinate the required VerifyNow calls.
Basic ID + supplied-reference Face Match
Use bundle: "facematch_verified" on POST /facematch. It combines basic SA ID verification with a selfie-to-reference-image comparison in one VerifyNow call. It does not fetch a Home Affairs photo.
Selfie + Home Affairs photo Face Match
Use bundle: "facematch" on POST /facematch. It obtains the supported Home Affairs reference photo and compares the submitted selfie in one VerifyNow call.
Bank Account Verification cannot currently be added to either Face Match bundle payload. It remains a separate VerifyNow request, with its own idempotency key and normal component charge.
Give your application one endpoint
Your frontend or partner calls one endpoint that you control. Your server keeps the API key private, runs the appropriate Face Match bundle and Bank Verification, then returns one combined response.
The example runs both checks in parallel because both are required. If Bank Verification is a step-up check, run it only after the identity and face result passes your policy so an unnecessary second call is not made.
POST /api/external/proof-of-address accepts multipart/form-data with document and mode (sandbox or production). Send x-api-key and a unique Idempotency-Key; reuse the key only when retrying identical input. One completed production result costs 3 credits, including a decline. Technical failures are refunded. Sandbox returns fictional data without provider processing or credits; use a fictional document for testing.
Accepted documents: utility bills, bank statements and government address documents issued within three months. PDF, JPG/JPEG, PNG, WebP and TIFF are supported, including multi-page PDFs. Direct requests support up to 4 MB. For files up to 15 MB, POST JSON with action: upload, mode: production, filename, size and content_type; PUT the file to uploadUrl with the returned headers; then POST mode and document_reference set to the returned reference. References expire after 15 minutes.
Optional fields: expected_first_name, expected_last_name, expected_address, expected_country (two- or three-letter code) and document_password. Compare results.name_on_document, address and formatted_address with your supplied values. results.status preserves the automated Approved or Declined decision; results.warnings contains code and message. Matching-only findings display as Review required in dashboard/PDF reports. Unprovided expected fields are omitted from those comparisons. A completed declined check is a valid verification result, not a technical error.
Document checks cover extracted details, age and signs of alteration or inconsistent metadata. No warning reported is not a guarantee that every forensic test ran, that a document is authentic or that someone resides there. Review findings under your acceptance policy.
Documents are used for processing and retry only. Temporary uploads are deleted after processing or expiry; documents are not archived. Results are held for up to 72 hours for safe retries. Billing, security and audit metadata is retained. Establish consent or another lawful basis and provide the required privacy notice before uploading. See /privacy and /terms.
Service and sample report: https://www.verifynow.co.za/services/proof-of-address#sample-report
API reference: https://www.verifynow.co.za/api-docs#proof-of-address
For South African ID inputs, you can run the standard ID checksum in your application before sending a verification request. This optional pre-flight validation catches typing errors early and can help avoid unnecessary calls. It is not a separate API step.
Driver's Licence Verification
Send the back-of-card image or complete barcode payload to POST /drivers-licence. The response includes the decoded licence fields, validation checks, categories and embedded portrait. Choose an additive bundle when the workflow also needs an identity record, Home Affairs Face Match, current selfie comparison or Passive Liveness.
Send a disc image or decoded barcode text to POST /vehicle-licence-disc. Choose a barcode or number plate comparison report. VIN comparison requires an enabled API account. Image integrations use visible field enrichment by default and can set include_visual_fields to false to skip it. allow_visual_fallback separately enables a visual-only result when the PDF417 barcode cannot be read.
POST /number-plate-lookup takes a South African registrationNumber and optional vin. When vin is supplied, vehicle.vinMatched reports whether it matches the returned VIN (case-insensitive, trimmed); missing returned VINs give false. Without vin, vinMatched is omitted. The lookup returns the registered make, model, description, year and VIN, plus confirmed manufacturer specifications for the variant. POST /vehicle-valuation/estimate takes make, model and year (optional variant, mileageKm and condition) and returns retail, market and trade values from the VerifyNow Valuation Engine. Each is charged separately and only when a result returns; no-result and failed requests use zero credits.
Send x-api-key and an Idempotency-Key. Sandbox plates DEMO123GP, DEMO190GP, DEMO191GP and DEMO192GP cover a result, no record, unavailable and no specifications. Sandbox valuation mileages 85090 and 85091 cover no valuation and an error. Allow up to 150 seconds for a plate lookup and 200 seconds for a valuation.
Authenticate a South African or supported foreign passport with POST /api/external/id-document-verify and bundle id_document_verification. Upload the full passport biodata page as front_image, or front_image_base64 for JSON. Include the page containing the MRZ. A second image is optional when the document requires another side or page. Production API requests use 2 credits per completed check. Basic SA ID verification is a separate 1-credit call when required.
Read results.id_verification for the document result. This example comes from a completed passport check on 10 October 2026. Personal details, dates and image data are replaced with placeholders to protect the passport holder. Additional fields, including image-quality scores and remainingCredits, can appear in the full response. Preserve nulls and missing fields when extraction supplies no value.
Holder nationality as a three-letter country code.
issuing_state / issuing_state_name
Issuing-country code and name. issuing_country is an optional request hint; the observed production response uses issuing_state.
date_of_birth
Date of birth in YYYY-MM-DD format.
expiration_date / date_of_issue
Expiry and issue dates in YYYY-MM-DD format, when extracted.
first_name / last_name / full_name
Extracted holder names.
portrait_image
Cropped portrait as a base64 JPEG string when extracted. Check that it is populated before Face Match.
front_image / back_image
Returned document images. back_image was null for the single-page passport example.
Machine-readable zone and check digits
The mrz object contains the decoded machine-readable zone. A passport uses the TD3 layout in the observed example. Check-digit validation forms part of MRZ checking. All five check digits in the observed production passport passed a local recalculation against the returned MRZ. The response supplies the check-digit values and error/warning arrays; it has no separate mrz_valid boolean in this example.
MRZ field
Meaning
mrz_type / mrz_string
Layout and raw MRZ text, with line breaks between the lines.
surname / name
Family and given names read from the MRZ.
country / nationality
Issuing-country and holder-nationality codes.
birth_date / expiry_date
MRZ dates in YYMMDD format. Use the top-level document dates for YYYY-MM-DD values.
document_type / document_number / sex
MRZ document type, passport number and sex marker.
optional_data / personal_number
Additional encoded information where present. These fields can contain identity numbers.
Printed check digits for the document number, date of birth and expiry date.
optional_data_hash / final_hash
Optional-data check digit where returned, and the composite check digit.
mrz_key
Composite MRZ key where returned.
errors / warnings
MRZ parsing and validation findings. Read these with the document-level warnings.
Document status and authenticity signals
Treat results.id_verification.status as an open string. The endpoint passes through the document decision; an exhaustive production enum has not been confirmed for this integration. The table explains client handling for the verdicts covered by the existing API guidance. Preserve additional values for review. HTTP 200 and success: true mean the request completed; your acceptance decision must use the document status, warnings and required fields.
Returned status
Client handling
Approved
Assess the passed document decision against your required fields and returned warnings. This was the observed production passport result.
Declined
Treat the document as a failed check and inspect the warnings.
In Review
Send the result to your review process. A returned review verdict is a completed response.
Other, missing or null
Preserve the raw value and send the result for review before acceptance.
Authenticity findings concern the submitted images. Document-level warnings contain a risk code, log_type severity and descriptions. The signal reference below describes documented document-check risks; the complete deployed warning-code set remains open. The observed passport returned warnings: [], mrz.errors: [] and mrz.warnings: []. The example includes image-quality scores. Separate numeric authenticity and tampering scores were absent. Treat absent forensic scores as unavailable evidence.
Signal reference
Meaning
MRZ_VALIDATION_FAILED
MRZ checksum or format validation failed.
MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME
MRZ data and visible document text disagree.
SCREEN_CAPTURE_DETECTED
The document image appears to have been captured from a screen.
PRINTED_COPY_DETECTED
The image appears to show a printed copy.
PORTRAIT_MANIPULATION_DETECTED
The document portrait appears altered or replaced.
DOCUMENT_EXPIRED
The detected document expiry date has passed.
This endpoint performs document-image checks. Issuing-authority record verification and NFC chip authentication require separate checks. A returned document decision should be considered together with your onboarding policy.
Use the passport portrait for Face Match
When the document meets your acceptance policy and portrait_image is populated, copy results.id_verification.portrait_image unchanged into reference_image_base64. Submit a current selfie as selfie_image_base64 to POST /api/external/facematch with bundle facematch_standard. This compares the two supplied images for South African and foreign passport holders. Each image has a maximum decoded size of 5 MB.
Face Match request body
{
"bundle": "facematch_standard",
"mode": "production",
"reference_image_base64": "<portrait_image from the document response>",
"selfie_image_base64": "<base64 selfie>"
}
Send x-api-key, Content-Type: application/json and a new Idempotency-Key for the Face Match operation. Reuse that key for retries with the same images. Read results.face_match.status and results.face_match.score. Face Match is a separate chargeable request. Assess selfie liveness through the separate Passive Liveness endpoint when your workflow requires it.
Request timing and retries
The initial passport request waits for processing and returns the completed result in that HTTP response. The processing call has a 55-second timeout. A concurrent retry with the same Idempotency-Key can return HTTP 202 with {"status":"pending"}. Repeat the same key and unchanged payload to retrieve a completed cached result. Processing failures and timeouts return HTTP 502. There is no passport job-polling URL or completion webhook in this endpoint.
Other request outcomes include 400 for invalid input, 401 for authentication failure, 402 for insufficient credits and 409 for an idempotency conflict or cached failure. Sandbox cooldown can return 429. The sandbox supplies mock data; use the production excerpt above to understand passport field placement.
Image transport, processing and retention
Images travel over HTTPS from your server to VerifyNow and onward to the document-processing service. HTTPS protects transport; the processing service decodes the image to analyse the document. The VerifyNow API runtime is configured for Cape Town. The processing service publishes AWS Ireland (EU) as its default region. Account-specific processing placement and cache replica/backup locations require confirmation for any contractual residency commitment.
The endpoint handles uploaded files for processing and does not write the original uploads to a document archive. Saved verification sessions are disabled for the processing request. The returned portrait and document images are included in the API response, and VerifyNow caches that complete response for up to 72 hours to support idempotent retries. This temporary cache is image retention. Cache expiry describes the active replay record; backup and operational-log retention require separate confirmation.
Supported passport issuing countries
The catalogue below lists passport-supported issuing countries and territories, including South Africa. Coverage was reviewed on 10 October 2026. Recognition depends on the document version and image quality. Use the passport issuing country when supplying the optional issuing_country hint; holder nationality is a separate response field. Catalogue entries include territories and special issuing authorities, so some codes are catalogue identifiers rather than ISO assignments.
Browse 218 passport issuing countries and territories
Catalogue reviewed 2026-10-10
218 of 218 entries
Code
Passport issuing country / territory
ABK
Abkhazia
AFG
Afghanistan
ALB
Albania
DZA
Algeria
AND
Andorra
AGO
Angola
AIA
Anguilla
ATG
Antigua and Barbuda
ARG
Argentina
ARM
Armenia
AUS
Australia
AUT
Austria
AZE
Azerbaijan
BHS
Bahamas
BHR
Bahrain
BGD
Bangladesh
BRB
Barbados
BLR
Belarus
BEL
Belgium
BLZ
Belize
BEN
Benin
BMU
Bermuda
BTN
Bhutan
BOL
Bolivia, Plurinational State of
BIH
Bosnia and Herzegovina
BWA
Botswana
BRA
Brazil
BRN
Brunei Darussalam
BGR
Bulgaria
BFA
Burkina Faso
BDI
Burundi
CPV
Cabo Verde
KHM
Cambodia
CMR
Cameroon
CAN
Canada
CYM
Cayman Islands
CAF
Central African Republic
TCD
Chad
CHL
Chile
CHN
China
COL
Colombia
COM
Comoros
COG
Congo
COD
Congo, The Democratic Republic of the
CRI
Costa Rica
HRV
Croatia
CUB
Cuba
CYP
Cyprus
CZE
Czechia
CIV
Côte d'Ivoire
DNK
Denmark
DJI
Djibouti
DMA
Dominica
DOM
Dominican Republic
DPR
Donetsk People's Republic
ECU
Ecuador
EGY
Egypt
SLV
El Salvador
GNQ
Equatorial Guinea
ERI
Eritrea
EST
Estonia
SWZ
Eswatini
ETH
Ethiopia
FRO
Faroe Islands
FJI
Fiji
FIN
Finland
FRA
France
GAB
Gabon
GMB
Gambia
GEO
Georgia
DEU
Germany
GHA
Ghana
GIB
Gibraltar
GRC
Greece
GRD
Grenada
GTM
Guatemala
GGY
Guernsey
GIN
Guinea
GNB
Guinea-Bissau
GUY
Guyana
HTI
Haiti
VAT
Holy See (Vatican City State)
HND
Honduras
HKG
Hong Kong
HUN
Hungary
ISL
Iceland
IND
India
IDN
Indonesia
IRN
Iran, Islamic Republic of
IRQ
Iraq
IRL
Ireland
IMN
Isle of Man
ISR
Israel
ITA
Italy
JAM
Jamaica
JPN
Japan
JEY
Jersey
JOR
Jordan
KAZ
Kazakhstan
KEN
Kenya
KIR
Kiribati
PRK
Korea, Democratic People's Republic of
KOR
Korea, Republic of
RKS
Kosovo
KWT
Kuwait
KGZ
Kyrgyzstan
LAO
Lao People's Democratic Republic
LVA
Latvia
LBN
Lebanon
LSO
Lesotho
LBR
Liberia
LBY
Libya
LIE
Liechtenstein
LTU
Lithuania
LPR
Lugansk People's Republic
LUX
Luxembourg
MAC
Macao
MDG
Madagascar
MWI
Malawi
MYS
Malaysia
MDV
Maldives
MLI
Mali
MLT
Malta
MHL
Marshall Islands
MRT
Mauritania
MUS
Mauritius
MEX
Mexico
FSM
Micronesia, Federated States of
MDA
Moldova, Republic of
MCO
Monaco
MNG
Mongolia
MNE
Montenegro
MSR
Montserrat
MAR
Morocco
MOZ
Mozambique
MMR
Myanmar
NAM
Namibia
NRU
Nauru
NPL
Nepal
NLD
Netherlands
NZL
New Zealand
NIC
Nicaragua
NER
Niger
NGA
Nigeria
MKD
North Macedonia
NOR
Norway
OMN
Oman
PAK
Pakistan
PLW
Palau
PSE
Palestine
PAN
Panama
PNG
Papua New Guinea
PRY
Paraguay
PER
Peru
PHL
Philippines
POL
Poland
PRT
Portugal
QAT
Qatar
ROU
Romania
RUS
Russian Federation
RWA
Rwanda
SHN
Saint Helena
KNA
Saint Kitts and Nevis
LCA
Saint Lucia
VCT
Saint Vincent and the Grenadines
WSM
Samoa
SMR
San Marino
STP
Sao Tome and Principe
SAU
Saudi Arabia
SEN
Senegal
SRB
Serbia
SYC
Seychelles
SLE
Sierra Leone
SGP
Singapore
SVK
Slovakia
SVN
Slovenia
SLB
Solomon Islands
SOM
Somalia
RSL
Somaliland
ZAF
South Africa
SSD
South Sudan
XOM
Sovereign Military Order of Malta
ESP
Spain
LKA
Sri Lanka
SDN
Sudan
SUR
Suriname
SWE
Sweden
CHE
Switzerland
SYR
Syrian Arab Republic
TWN
Taiwan
TJK
Tajikistan
TZA
Tanzania, United Republic of
THA
Thailand
TLS
Timor-Leste
TGO
Togo
TON
Tonga
TTO
Trinidad and Tobago
TUN
Tunisia
TKM
Turkmenistan
TCA
Turks and Caicos Islands
TUV
Tuvalu
TUR
Türkiye
UGA
Uganda
UKR
Ukraine
ARE
United Arab Emirates
GBR
United Kingdom
USA
United States
URY
Uruguay
UZB
Uzbekistan
VUT
Vanuatu
VEN
Venezuela, Bolivarian Republic of
VNM
Viet Nam
VGB
Virgin Islands, British
ESH
Western Sahara
YEM
Yemen
ZMB
Zambia
ZWE
Zimbabwe
ALA
Åland Islands
4
Understand Idempotency
Prevent duplicate charges on retries
Required for Production
The Idempotency-Key header is required for all production API calls. It prevents duplicate charges.
How It Works
Generate a unique key (UUID) for each unique request
Send this key in the Idempotency-Key header
If you retry with the same key, you get the cached response (no duplicate charge)
Keys expire after 72 hours
What Counts as Duplicate
Scenario
Result
Same Key + Same Body
Returns cached response (no charge)
Same Key + Different Body
409 Conflict error
Different Key + Same Body
New request (charges credits)
5
Test in Sandbox Mode
Risk-free testing before going live
Before going live, test everything with sandbox mode:
Repeating the same sandbox payload from the same IP returns 429 after a 2-second cooldown. Distinct reserved inputs run immediately. Playground, Postman, and curl share this lock.
6
Handle Errors
Graceful error handling for production
Always handle API errors gracefully:
Code
Meaning
Action
200
Success
Process the response
400
Invalid parameters
Check your request body
401
Invalid API key
Check your API key
402
Insufficient credits
Top up your account
409
Idempotency conflict
Use a new Idempotency-Key
429
Rate limited
Slow down requests
7
Go Live
Deploy to production
When ready for production:
Switch to production mode:"mode": "production"
Ensure you have credits - Check balance via GET /my_credits
Always include Idempotency-Key for production requests
Monitor your usage in the VerifyNow dashboard
Security Checklist
API key stored as environment variable
API key never exposed in client-side code
Idempotency-Key used for all production requests
Error handling implemented
Tested in sandbox mode first
Property Search by ID
Send a valid South African ID number to POST /property-search. Production requests need an Idempotency-Key.
A completed production search uses the current credits shown on the pricing table, including a result with found: false.
Start a job with POST /africa-verification, then fetch its result from GET /africa-verification/jobs/{jobId}.
The production POST uses the current credits shown on the pricing table. Status requests use 0 credits.
Zimbabwe uses country: ZW and id_type: NATIONAL_ID_NO_PHOTO. Poll every 3 seconds while pending and stop on completed or failed. Sandbox creates a completed mock job whose result is available through GET.
Job acceptance confirms submission. Read the completed result to determine the identity outcome. Production results with code 1012 (match) or 1013 (no matching record) use the configured credits when the job completes; failed jobs and status requests use 0 credits.
Use POST /api/external/adverse-media with name, entity (0 Person or 1 Company), and mode (sandbox or production). Supply x-api-key; production also requires an Idempotency-Key of 8–160 characters.
{"name":"Jane Example 90","entity":0,"mode":"sandbox"}
Read results.articles for article evidence and results.screening for available premium screening findings. A no-record result (code 4) returns HTTP 200 with credits_used: 0. Other completed searches use the configured credits, including results with no articles. Sandbox uses zero credits. Review potential matches against the source evidence.
Retry the same payload with the same key within 48 hours for an encrypted replay without another charge. Handle 202 and 429 using Retry-After. Names ending in 90 return no sandbox findings; 91 simulates failure. This separate endpoint does not enrol a subject.
/aml-screening is the one-shot screen. /aml-ongoing enrols that customer and rescreens them later. Sandbox and production ongoing responses include results.Header.DatasetVersion and results.Header.DatasetPublishedAt. VerifyNow AML is a licensed ongoing AML and ODD API. Enrol, rescreen, and withdraw identified customers with name plus identifier. A dataset webhook and email notify list changes; rescreen remains your call. Set the HTTPS URL under Settings → Ongoing AML → Dataset update webhook. Credentials and the production path are issued after the licence. Read the VerifyNow AML webhook setup.
Consumer/Person Trace: All-in-One Endpoint
The Consumer/Person Trace endpoint (reportType: "consumer_trace") returns ALL of the following in a single call:
AddressData
Current and historical addresses (residential & postal)
EmploymentData
Employment history with employer names
ContactData
Phone numbers (cell and landline)
DefiniteMatchData
ID verification details
No need to make separate calls for address, employment, or phone data - it's all included.
POST /api/external/foreign-bank-account-verification supports South African bank accounts held by foreign passport holders. Send firstName, surname, passportNumber, passportCountry (two-letter ISO country code), bankName, bankAccountNumber, bankBranchCode, bankAccountType, consentConfirmed: true, purpose and mode. Use x-api-key, Content-Type: application/json and an Idempotency-Key of 8–160 characters in both modes.
A completed real-time check returns HTTP 200 with processingMode: "realtime", status: "completed", requestId, creditsUsed and result. Inspect result.outcome and result.checks to decide whether a payment needs review. This response creates no job or webhook. Foreign-passport checks use the standard bank-account verification credit price, with a fallback configuration of 6 credits. See /pricing#foreign-bank-account-verification for the configured price.
Account age: lengthOpen in standard bank results and the legacy accountNumberLengthValid field in business, NPO and foreign-passport checks indicate whether the account has been open for at least three months. Yes/true means at least three months; No/false means under three months; unavailable/null means the bank did not supply the result. Existing API field names are retained for compatibility.
Supply webhookUrl and webhookSecret together to enable asynchronous fallback. If real-time verification cannot complete and these fields are present, HTTP 202 returns a jobId for status reads and signed callbacks. Without webhook fields, fallback returns HTTP 503, code ASYNC_FALLBACK_REQUIRES_WEBHOOK and creditsUsed: 0. The asynchronous timing, job recovery and webhook examples below apply to this fallback and to Capitec Business.
Sandbox uses synthetic details and zero credits. Omit webhook fields for the real-time sandbox response; include both fields to exercise the asynchronous sandbox flow. Production retries must retain the original body and Idempotency-Key. A changed body needs a new key; do not treat a job or an HTTP success alone as a positive account match.
Capitec Business and Mercantile Bank company checks use POST /api/external/business-bank-account-verification, branch code 450105, and the separate business-bank price (fallback configuration: 7 credits). Send companyRegistrationNumber as a string containing the registration or identity number held by the bank. Existing CIPC and 13-digit SA ID formats retain their handling. Other strings, including trust and NPO identifiers, preserve letters, slashes and hyphens; there is no identifier format or length check. Matching depends on bank support and records. Concurrent submissions are accepted with separate Idempotency-Keys for new verifications; the bank verification service queues accepted batch jobs, so completion timing depends on bank processing. Batch processing can take several hours; requests after the bank’s cut-off may wait for the next processing window. Their response remains HTTP 202 with a jobId. See /api-docs/foreign-bank-account-verification for the response examples and webhook recovery guide.
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.
Request field limits
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.
The completed example is a sandbox fixture. The failed example illustrates a production failure; sandbox suffix 91 returns an HTTP error before job creation.
Use the full NPO name. Use the full NPO name recorded by the bank for the account-name check. Abbreviated account labels can return a name mismatch.
This is an asynchronous check. POST /api/external/npo-bank-account-verification returns HTTP 202 with a job ID. Read the saved result or receive a signed webhook when bank processing finishes. Processing can take several hours or the next banking window.
Request
Send x-api-key, Content-Type: application/json and a fresh Idempotency-Key for a new check. Keep the same key and body when retrying an uncertain submission.
{
"companyName": "Example Community Organisation",
"bankName": "ABSA",
"bankAccountNumber": "1234567889",
"bankBranchCode": "632005",
"bankAccountType": "current",
"consentConfirmed": true,
"purpose": "Verify the organisation bank account",
"webhookUrl": "https://your-domain.example/webhooks/verifynow",
"webhookSecret": "replace-with-your-own-secret-at-least-32-characters",
"mode": "sandbox"
}
idnumber is optional; companyRegistrationNumber is an alias. If both are supplied, their values must agree. Enter the registration/ID number held by the bank when available. Omitted fields are reported as Not provided.
The account number must contain 7–13 digits and the branch code six digits. The endpoint accepts the bank name and branch code supplied; supported coverage depends on the bank. Supply the full NPO name in companyName (up to 160 characters) for a verified outcome. The API accepts a request with this field omitted; its completed result has a review outcome and reports the name check as Not provided. Account type is optional. Account types: current, cheque, savings, transmission, bond, credit-card or unknown.
consentConfirmed must be true. Purpose is 3–160 characters; webhookSecret is 32–256 characters. Supply a public HTTPS webhook URL. Mode is sandbox or production.
Result and missing ID
Verified means the account was found, is open and matches the full NPO name. A supplied account type or identifier must also match. An omitted ID remains Not provided and does not cause review. Missing or mismatched required checks return review.
checks.surnameMatch reports whether the supplied companyName matches the NPO account name held by the bank. This field keeps its existing API name. The response also retains initialsMatch; initials are optional and are excluded from the NPO outcome.
GET /api/external/npo-bank-account-verification/jobs/{jobId} returns the owned job and its result at zero credits. Results are withheld while billing is pending.
POST /api/external/npo-bank-account-verification/jobs/{jobId}/retry-webhook with {} redelivers the saved result. Supply both webhook fields to change the receiver. It does not create another bank enquiry.
Events are npo_bank.verification.completed and npo_bank.verification.failed. Verify the HMAC-SHA256 signature over the timestamp and raw body, reject stale timestamps and deduplicate event IDs. Follow the bank webhook guide for signing and recovery. A job without a final result times out after 48 hours.
Sandbox and billing
Sandbox uses synthetic data and zero credits. Account numbers ending in 90 return review; 91 simulates a submission failure. Other valid sandbox account numbers return positive name/account checks. Missing IDs remain Not provided.
For a specific case, send x-verifynow-sandbox-scenario with mode: sandbox and a fresh Idempotency-Key. This explicit scenario takes precedence over account suffixes. The header is ignored in production.
Scenario
Outcome
Expected behaviour
verified_without_id
verified
Use the full name and omit both identifier fields. ID remains Not provided.
name_mismatch
review
The supplied NPO name does not match.
account_not_found
review
Account found and open are false.
closed_account
review
The account is found but closed.
account_type_mismatch
review
Supply a known account type; its match is false.
identity_mismatch
review
Supply an identifier; its match is false.
name_unavailable
review
The bank name-match result is unavailable (null).
verification_timed_out
failed
A failed callback carries verification_timed_out.
Use https://www.verifynow.co.za/api/bank-verification/callback-check as a sandbox receiver with your own signing secret. Your production integration should use its own HTTPS receiver. Poll saved jobs at zero credits.
Production uses the configured NPO service price shown on pricing. Completed results, including review, use credits. Failed verifications use zero customer credits. Keep sufficient credits available until processing finishes.
Bank job status and report recovery
This section covers asynchronous submissions and fallback jobs. Completed real-time foreign-passport responses use a requestId and return the result in the POST response.
Foreign passport and Capitec Business submissions return a jobId. Use GET /api/external/foreign-bank-account-verification/jobs/{jobId} or GET /api/external/business-bank-account-verification/jobs/{jobId} with the submitting account’s API key to read status and saved results at zero credits.
POST an empty JSON object to the job URL followed by /retry-webhook to redeliver a completed result. Provide webhookUrl and webhookSecret together to change the receiver. The playground includes both recovery actions for sandbox and production jobs. Dashboard reports include the requester, submitted details and elapsed run time, with authenticated PDFs available while the submitted details remain within their seven-day retention period.