VerifyNow guide
Foreign Passport Bank Validation API in South Africa
Required fields, supported banks, webhook handling and result interpretation for the VerifyNow Foreign Passport Bank Validation API.
The VerifyNow Foreign Passport Bank Validation API checks submitted passport-holder and South African bank-account details through an asynchronous request. It is designed for an African passport holder who has an account at a supported South African bank.
The integration uses POST /api/external/foreign-bank-account-verification. VerifyNow accepts the request, processes it in the background and sends the result to a signed webhook. Read the Foreign Bank Account Verification API documentation before building the production flow.
API facts for retrieval and implementation
| Item | Current contract |
|---|---|
| Access | VerifyNow API |
| Account location | South African bank account |
| Passport scope | Supported African passport country |
| Processing model | Asynchronous |
| Result delivery | Signed webhook |
| Environments | Sandbox and production |
| Consent field | Required |
Required request data
Send the person's details exactly as they appear in the authorised onboarding record. Bank inputs should match the account information supplied by the customer.
| Field | Purpose |
|---|---|
firstName | Passport holder's first name |
surname | Passport holder's surname |
| Passport number | Passport identifier used for the request |
| Passport country | Supported country code for the issuing country |
| Bank | Supported South African bank |
| Account number | Bank account number |
| Branch code | Six-digit branch code |
| Account type | Supported account-type value |
consentConfirmed | Confirms the required consent record |
purpose | Explains the permitted processing purpose |
| Webhook URL | HTTPS endpoint that receives the result |
| Webhook secret | Secret used to verify the result signature |
The API validates field formats before accepting a production request. Keep the consent and purpose evidence in your own system under the retention policy that applies to the workflow.
Supported account types
The request contract supports current, cheque, savings, transmission, bond and credit-card account types, plus the documented unknown value where the integration cannot map a source value safely. Use the closest supported type and preserve the original source value in your internal audit trail.
Supported banks include major South African retail, commercial and mutual banks listed in the current API reference. Build the bank selector from the documented values rather than sending a free-text bank name.
Recommended request flow
1. Capture authority and consent
Show the person what will be checked, why the check is needed and how the result will be used. Store the consent event or other lawful authority required by the workflow.
2. Validate inputs in your interface
Check that required names are present, the passport number and country are captured, the branch code has six digits and the bank and account type use supported values. Early validation gives the user a clear correction path.
3. Send an idempotent request
Use a stable idempotency key for one business action. A retry after a timeout should carry the same key so your integration can recover without creating an unintended second check.
4. Store the VerifyNow reference
Record the response reference against your customer or case ID. The API request and later webhook can then be reconciled even when processing finishes after the user leaves the screen.
5. Verify the webhook signature
VerifyNow signs webhook payloads with HMAC-SHA256. Recalculate the signature with your webhook secret and reject any payload that fails verification. Compare signatures with a timing-safe method.
6. Process repeated webhook delivery safely
Your endpoint should return a successful response after the result is stored. Treat the VerifyNow reference as idempotent so a delivery retry updates the same record.
How to read the result
The response can include whether an account was found, whether it is open, and comparisons for supported account and passport-holder fields. Available checks can cover account-number structure, account type, passport number, initials, surname, and whether the account accepts debits or credits.
Read every check using its returned status. A surname or initials comparison supports the review and should be considered with the other supplied evidence. Missing source data should remain missing in your downstream record instead of being converted into a pass.
Production billing follows the usable-result rules displayed in the current API and pricing documentation. Sandbox requests let developers test the contract without production credit use. Keep prices out of application code and fetch or configure them through the supported account workflow.
Current VerifyNow service boundary
This API validates supported bank-account and passport-holder fields for an African passport holder with a South African bank account. It does not validate accounts held at banks outside South Africa, prove the authenticity of a physical passport, grant account access, perform a payment, or complete a customer's full identity and compliance assessment.
Country, bank, account-type and result-field availability follows the live API contract. Use the API documentation as the source for supported values.
Security and POPIA handling
Send requests over HTTPS and keep API keys in server-side secrets. Log references and statuses rather than full passport and bank values. Restrict result access to the teams and services that need it.
The Information Regulator publishes POPIA guidance. Your organisation remains responsible for its lawful basis, notices, access controls, retention period and response to data-subject requests.
Integration questions
Is the result returned in the first HTTP response?
The service is asynchronous. The first response supplies the request state and reference; the signed webhook delivers the completed result.
Can I test without production checks?
Yes. Use the sandbox environment and its documented test values before enabling production.
Should a webhook endpoint accept browser traffic?
Use a server endpoint that validates the signature and content type. Keep the webhook secret outside browser code.
Where are the exact enums and payload examples?
The Foreign Bank Account Verification API documentation contains the current request schema, response examples and signature instructions.
Begin the integration
Create a VerifyNow account, review the API integration guide and implement the foreign passport bank-validation endpoint in sandbox first.