Account Verification API
Endpoint: {server}/api/avs/v1/ — see Getting started for the server URL, authentication and JSON Web Tokens.
API Post Functions
verifyAccount
Endpoint: {server}/api/avs/v1/verifyAccount
verifyAccount: POST FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| token | Text | Y | The signed JWT |
| test | Boolean | O | Set to true if testing. This will bypass billing and will only validate test data |
| customerReference | Text | Y | Your unique customer reference identifier |
| accountType | Text | Y | The account type. Either current or savings |
| accountNumber | Text | Y | The account number |
| branchCode | Text | Y | The account branch code |
| identificationType | Text | Y | Identification type. Possible values are: SID - South African ID SPP - Passport number SBR - Business registration number TRN - Trust number |
| identificationNumber | Text | Y | The account holder's identity, passport, company registration or trust number |
| name | Text | Y | The accountholder last name or company/trust name |
| initials | Text | CY | The account holder's initials. Needed for ID Types of SID or SPP |
| taxReference | Text | O | The account holder's tax reference. Nedbank Only. |
| emailAddress | Text | O | The account holders email address |
| cellNumber | Text | O | The account holders cell phone number |
verifyAccount: RESPONSE FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| jti | Text | Y | The unique JWT ID |
| Status | Text | Y | Success or Failed |
| message | Text | O | The failure message |
| customerReference | Text | CY | Your unique customer reference identifier |
| accountExists | Text | CY | F - Failed pre-validation N - No U - Unprocessed Y - Yes |
| identificationNumberMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| initialsMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| nameMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| accountActive | Text | CY | N - No U - Unprocessed Y - Yes |
| accountDormant | Text | CY | N - No U - Unprocessed Y - Yes |
| accountActive3Months | Text | CY | N - No U - Unprocessed Y - Yes |
| canDebitAccount | Text | CY | N - No U - Unprocessed Y - Yes |
| canCreditAccount | Text | CY | N - No U - Unprocessed Y - Yes |
| taxReferenceMatch | Text | CY | N - No U - Unprocessed Y - Yes |
| accountTypeMatch | Text | CY | N - No U - Unprocessed Y - Yes |
| emailMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| cellNumberMatched | Text | CY | N - No U - Unprocessed Y - Yes |
Example verifyAccount Post:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"customerReference": "Ref1",
"accountType": "current",
"accountNumber": "700000000",
"branchCode": "051001",
"identificationType": "SID",
"identificationNumber": "200802751907",
"name": "SOAP",
"initials": "J",
"emailAddress": "joesoap@somemail.com ",
"cellNumber": "0823456789"
}
Example verifyAccount JSON response:
Example pending — this example could not be reconstructed reliably from the source document and is being prepared.
verifyAccounts
Endpoint: {server}/api/avs/v1/verifyAccounts
verifyAccounts: POST FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| token | Text | Y | The signed JWT |
| test | Boolean | O | Set to true if testing. This will bypass billing and will only validate test data |
| account | Array | Y | 1-n of account data |
verifyAccounts: ACCOUNT DATA FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| customerReference | Text | Y | Your unique customer reference identifier |
| accountType | Text | Y | The account type. Either current or savings |
| accountNumber | Text | Y | The account number |
| branchCode | Text | Y | The account branch code |
| identificationType | Text | Y | Identification type. Possible values are: SID – South African ID SPP – Passport number SBR – Business registration number TRN – Trust number |
| identificationNumber | Text | Y | The account holder's identity, passport, company registration or trust number |
| name | Text | Y | The accountholder last name or company/trust name |
| initials | Text | O | The account holder's initials |
| taxReference | Text | O | The account holder's tax reference. Nedbank Only. |
| emailAddress | Text | O | The account holders email address |
| cellNumber | Text | O | The account holders cell phone number |
verifyAccounts: RESPONSE FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| Jti | Text | Y | The unique JWT ID |
| status | Text | Y | Processed |
| accounts | Array | Y | 1-n of status fields |
verifyAccounts: STATUS FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| customerReference | Text | Y | Your unique customer reference identifier |
| accepted | Boolean | Y | True or False |
| reason | Text | O | Failure reason |
NB: A post-back URL must be set in the console for the verification results to be sent to. This is set in Setup – General Settings – API Settings. You may have more than one Access Token so add to the correct one.
The receiving code for the post-back MUST return "Received" in plain text as part of the receiving process. If this is not returned the system will repost for up to 60 seconds before abandoning the post-back.
verifyAccounts: POST-BACK RESULTS FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| jti | Text | Y | The unique JWT ID |
| status | Text | Y | Success or Failed |
| message | Text | O | The failure message |
| customerReference | Text | CY | Your unique customer reference identifier |
| accountExists | Text | CY | F - Failed pre-validation N - No U - Unprocessed Y - Yes |
| identificationNumberMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| initialsMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| nameMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| accountActive | Text | CY | N - No U - Unprocessed Y - Yes |
| accountDormant | Text | CY | N - No U - Unprocessed Y - Yes |
| accountActive3Months | Text | CY | N - No U - Unprocessed Y - Yes |
| canDebitAccount | Text | CY | N - No U - Unprocessed Y - Yes |
| canCreditAccount | Text | CY | N - No U - Unprocessed Y - Yes |
| taxReferenceMatch | Text | CY | N - No U - Unprocessed Y - Yes |
| accountTypeMatch | Text | CY | N - No U - Unprocessed Y - Yes |
| emailMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| cellNumberMatched | Text | CY | N - No U - Unprocessed Y - Yes |
| completeMatch | Text | CY | N - No U - Unprocessed Y - Yes |
Example verifyAccounts Post:
:::warning Source conflict — confirm before use
This example uses email and cellphone, while the ACCOUNT DATA FIELDS table above specifies emailAddress and cellNumber. The source document is inconsistent here and the correct field names have not been confirmed with the platform team.
:::
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"account": [
{
"customerReference": "Ref1",
"accountType": "current",
"accountNumber": "700000000",
"branchCode": "051001",
"identificationType": "SID",
"identificationNumber": "200802751907",
"name": "SOAP",
"initials": "J",
"email": "joesoap@somemail.com ",
"cellphone": "0823456789"
},
{
"customerReference": "Ref2",
"accountType": "current",
"accountNumber": "700000000",
"branchCode": "051001",
"identificationType": "SID",
"identificationNumber": "200703363307",
"name": "DoleIndustries PTY Ltd.",
"email": "bdole@somemail.com ",
"cellphone": "0723456789"
}
]
}
Example verifyAccounts JSON Response:
{
"jti": "{UNIQUE VALUE}",
"status": "Processed",
"accounts": [
{
"customerReference":"Ref1", "accepted":true
},
{
"customerReference":"Ref2", "accepted":false,
"reason": " Check Digit Verification Failed"
}
]
}
Example verifyAccounts JSON post back:
Example pending — this example could not be reconstructed reliably from the source document and is being prepared.
checkDigitVerification
Endpoint: {server}/api/avs/v1/checkDigitVerification
This is a basic account data verification to verify that the account type, account number and branch code are structurally correct.
checkDigitVerification: POST FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| token | Text | Y | The signed JWT |
| accountType | Text | Y | The account type. Either current or savings |
| accountNumber | Text | Y | The account number |
| branchCode | Text | Y | The account branch code |
checkDigitVerification: RESPONSE FIELDS
| Name | Type | Required | Description |
|---|---|---|---|
| jti | Text | Y | The unique JWT ID |
| status | Text | Y | Success or Failed |
| message | Text | CO | The failure message if failed |
| bank | Text | CO | The bank name if successful |
Example checkDigitVerification Post:
Example pending — this example could not be reconstructed reliably from the source document and is being prepared.
Example checkDigitVerification JSON response:
{
"jti": "{UNIQUE VALUE}",
"status": "Failed",
"message":" Check Digit Verification Failed"
}
Errors
If there is any submission error relating to authentication or missing fields the response fields will be:
- status: The status will be Error
- error: The error message
Example Error Message:
{
"status": "Error",
"error": "Token secret verify fail"
}
Test Data
For testing AVS, the following data may be used.
Defaults:
Account Type: current
Branch Code: 145710
| Account Number | ID Type | ID Number | Initials | Last Name | Email Address | Cell Number |
|---|---|---|---|---|---|---|
| 1002301378 | SPP | HG7072J76211 | ML | ATKINSON | MEG@ROCKANDHERR.COM | 0997309627 |
| 1001014138 | SBR | 200802751907 | BROLL PROPERTY GROUP PTY LTD | 0993210934 | ||
| 1001036875 | SID | 8009130202081 | DE | DOOLEY | DANIELLEDOOLEY@GMAIL.COM | 0998155218 |
Participating Banks
See Participating banks for the Real-time AVS participating bank list.