Real-time bank account verification (BANVR)
Overview
A BANVR request submits data to verify a single account number against the information provided. Real-time account verification has a guaranteed response time of 60 seconds from the bank. If a response is not received in 60 seconds, there is no result. Because the response occurs in real-time, a callback URL is not supplied as there is no callback.
Request URL
https://www.peachpay.co.za/API/RealtimeVerification?key=yourkey
Request structure
A BANVR request consists of three separate sections with a root parameter called APIRealTimeVerificationRequest
. The Header
section contains information on the BANVR batch, the Records
section is a collection of account details for verification (a single account is valid for real-time verification), and the Totals
section verifies that the information sent is complete and correct.
Header
A BANVR request has a single Header
section with the following parameters:
Parameter | Description | Condition |
---|---|---|
PsVer | The version of the Peach Payments file format. 2.0.1. | Required |
Client | Your unique client code. | Required |
Reference | The batch reference. Allows you to identify the batch in the reports and the verification responses. | Required |
UniqueId | Used to prevent duplicate requests. | Optional |
CallBackUrl | If you supplied a callback URL and the real-time verification fails, a standard BANV service executes and sends the results to the supplied callback URL. | Optional |
Records
A BANVR request has a single Records
section with a single FileContents
sections with the following parameters:
Parameter | Description | Condition |
---|---|---|
Initials | The account holder's initials. | Optional |
Name | The account holder's (or company's) name. | Required |
IdNumber | The account holder's ID, passport, or company registration number. | Optional |
AccountNumber | The account number for verification. | Required |
BranchCode | The branch code of the account number. | Required |
Reference | A transaction reference. Used to uniquely identify a verification record. | Optional |
Totals
A BANVR request has a single Totals
section with the following parameters:
Parameter | Description | Condition |
---|---|---|
Records | The total number of BANVR records submitted. | Required |
BranchHash | The sum of all the branch codes for the BANVR record. | Required |
AccountHash | The sum of all the account numbers for the BANVR record. | Required |
Example request
<APIRealTimeVerificationRequest>
<Header>
<PsVer>2.0.1</PsVer>
<Client>ZER001</Client>
<Reference>TEST BANVR</Reference>
<CallBackUrl>https://example.com/Callback</CallBackUrl>
</Header>
<Records>
<FileContents>
<Name>BARISHMAN</Name>
<Initials>A</Initials>
<IdNumber>4012155047088</IdNumber>
<AccountNumber>1021278653</AccountNumber>
<Reference>12345</Reference>
<CustomerCode>C12345C</CustomerCode>
<BranchCode>198765</BranchCode>
</FileContents>
</Records>
<Totals>
<Records>1</Records>
<BranchHash>198765</BranchHash>
<AccountHash>1021278653</AccountHash>
</Totals>
</APIRealTimeVerificationRequest>
Response structure
The standard response structure includes a BanvRealtimeResult
parameter containing the validation results.
The Response
root parameter consists of the following parameters:
Parameter | Description |
---|---|
Result | Always OK . |
BatchCode | The unique code for the batch that the validation belongs to. |
The BanvRealTimeResult
section consists of the following parameters:
Parameter | Description |
---|---|
AccountNumber | The account number you are verifying. |
IDNumber | The account holder's ID, passport, or company registration number. |
Initials | The account holder's initials. |
Name | The account holder's or company's name. |
Reference | The batch reference. Allows you to identify the batch in the reports. |
Flags | Y , N , and blank characters mean a corresponding result. See below for details. |
Result | The result status is a text representation of the verification result. |
If the API could not process the real-time verification, the Result
field is Unprocessed
and the Flags
field is U
.
The CDVResults
parameter is always returned regardless of whether the account passed the CDV check.
The Result
section consists of the following parameters:
Parameter | Description |
---|---|
Result | The result of the CDV check. Always Invalid for a failed account. |
Message | The rejection reason. |
AccountNumber | The account number that failed the CDV test. |
BANV flags
The flags of the verification result are a character indication of each of the eight verification options. Not all banks are able to provide all the information, in which case, the character is a blank space. An example Flags
parameter is YYYYYYYY
, which means A/c exists, ID matches, Inits match, Name matches, A/c open, accepts Dr, accepts Cr & open more than 3 months
.
If the first five flags are Y
, the account is valid.
Names and initials must be the same as those that the bank has on record. If the Initials provided are
WJ
and the bank hasW
on record, the initials flag isN
.
The eight flag options are:
- Account exists
- ID number or company registration matches
- Initials match (should be blank to match for company)
- Surname or company name matches
- Account open
- Account accepts debits
- Account accepts credits
- Account open for three or more months
Example response
<Response>
<Result>OK</Result>
<BatchCode>35308</BatchCode>
<TotalFeeExcludingVAT>0.00</TotalFeeExcludingVAT>
<BanvRealtimeResult>
<AccountNumber>1021278653</AccountNumber>
<IDNumber>4012155047088</IDNumber>
<Initials>A</Initials>
<Name>BARISHMAN</Name>
<Reference>12345</Reference>
<Flags>YYYNYYYY</Flags>
<Result>A/c exists, ID matches, Inits matches, Name doesn't match, A/c open, accepts Dr, accepts Cr & open more than 3 months</Result>
</BanvRealtimeResult>
<CDVResults>
<Result>
<Result>Valid</Result>
<AccountNumber>1021278653</AccountNumber>
<BranchCode>198765</BranchCode>
<Reference>12345</Reference>
<CustomerCode>C12345C</CustomerCode>
</Result>
</CDVResults>
</Response>
Postman collection
See the Peach Payments Postman collection for sample calls.
Updated over 1 year ago