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, no result is returned. Due to the real-time response, no callback URL is supplied as no callback is sent.

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 relating to the BANVR batch, the Records section is a collection of account details to be verified (only a single account is valid for real-time verification), and the Totals section verifies that the information being sent is complete and correct.

Header

A BANVR request has a single Header section with the following parameters:

ParameterDescriptionCondition
PsVerThe version of the Peach Payments file format. Currently 2.0.1.Required
ClientYour unique client code.Required
ReferenceThe batch reference. Allows you to identify the batch in the reports and the verification responses.Required
UniqueIdUsed to prevent duplicate requests.Optional
CallBackUrlIf a callback URL is supplied and the real-time verification fails, a standard BANV service is used and the results are sent to the callback URL supplied.Optional

Records

A BANVR request has a single Records section with a single FileContents sections with the following parameters:

ParameterDescriptionCondition
InitialsThe account holder's initials.Optional
NameThe account holder's (or company's) name.Required
IdNumberThe account holder's ID, passport, or company registration number.Optional
AccountNumberThe account number to be verified.Required
BranchCodeThe branch code of the account number to be verified.Required
ReferenceA transaction reference. Can be used to uniquely identify a verification record.Optional

Totals

A BANVR request has a single Totals section with the following parameters:

ParameterDescriptionCondition
RecordsThe total number of BANVR records submitted.Required
BranchHashThe sum of all the branch codes for the BANVR record.Required
AccountHashThe 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 is returned with a BanvRealtimeResult parameter containing the validation results.

The Response root parameter consists of the following parameters:

ParameterDescription
ResultAlways OK.
BatchCodeThe unique code for the batch that the validation belongs to.

The BanvRealTimeResult section consists of the following parameters:

ParameterDescription
AccountNumberThe account number of the account being verified.
IDNumberThe account holder's ID, passport, or company registration number.
InitialsThe account holder's initials.
NameThe account holder's or company's name.
ReferenceThe batch reference. Allows you to identify the batch in the reports.
FlagsY, N, and blank characters indicate a corresponding result. See below for details.
ResultThe result status is a text representation of the verification result.

If the real-time verification could not be processed, the Result​ field ​is Unprocessed and the Flags ​field is U.

The CDVResults parameter is always returned regardless of whether or not the account passed the CDV check.

The Result section consists of the following parameters:

ParameterDescription
ResultThe result of the CDV check. Always Invalid for a failed account.
MessageThe reason for the rejection.
AccountNumberThe 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 supply all the information, in which case, the character is a blank space. An example Flags parameter is YYYYYYYY, which is the equivalent to a result of 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 can be considered valid.

📘

Names and initials must be identical to the names and initials that the bank has on record, otherwise they won't match. If the Initials provided are WJ and the bank has W on record, the initials flag is N.

The eight flag options are:

  1. Account exists
  2. ID number or company registration matches
  3. Initials match (should be blank to match for company)
  4. Surname or company name matches
  5. Account open
  6. Account accepts debits
  7. Account accepts credits
  8. 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 &amp; 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>