Bank account verification (BANV)

Overview

A BANV request submits data to verify a batch of account numbers against the information provided. When a batch has been submitted, a CDV check is performed on the account details provided and any accounts failing that check are included in the response. Any accounts that pass the CDV check continue to be processed.

Request URL

https://www.peachpay.co.za/API/Verification?key=yourkey

Request structure

A BANV request consists of three separate sections with a root parameter called APIVerificationRequest. The Header section contains information relating to the BANV batch, the Records section is a collection of account details to be verified, and the Totals section verifies that the information being sent is complete and correct.

Header

A BANV 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
ServiceThe code for the service being used. BANV for bank account verification.Required
ReferenceThe batch reference. Allows you to identify the batch in the reports and the verification responses.Required
CallBackUrlThe callback URL to be used to send back verification responses.Required
UniqueIdUsed to prevent duplicate requests.Optional

Records

A BANV request has a single Records section with multiple 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 BANV request has a single Totals section with the following parameters:

ParameterDescriptionCondition
RecordsThe total number of BANV records submitted.Required
BranchHashThe sum of all the branch codes for the BANV records.Required
AccountHashThe sum of all the account numbers for the BANV records.Required

Example request

<APIVerificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:/www.w3.org/2001/XMLSchema">
  <Header>
    <PsVer>2.0.1</PsVer>
    <Client>CLI001</Client>
    <Service>BANV</Service>
    <Reference>5621-28/02/13</Reference>
    <CallBackUrl>http://yourURL.com/Callback</CallBackUrl>
  </Header>
  <Records>
    <FileContents>
      <Initials>EX</Initials>
      <Name>Example Name</Name>
      <IdNumber>5511255173885</IdNumber>
      <AccountNumber>123456789101</AccountNumber>
      <BranchCode>632005</BranchCode>
      <Reference>5621-123456789101</Reference>
    </FileContents>
  </Records>
  <Totals>
    <Records>1</Records>
    <BranchHash>632005</BranchHash>
    <AccountHash>123456789101</AccountHash>
  </Totals>
</APIVerificationRequest>

Response structure

The standard response structure is returned. All response data is submitted as form data in a POST action, for example, application/x-www-form-urlencoded with the response key.

If any of the BANV FileContents records failed the CDV check, they are returned as a CDVResults parameter with a collection of Result parameters outlining the reasons for the account rejection. 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.

📘

If any of the accounts passed the CDV check, the batch is accepted and proceeds to be verified by the bank.

Example response

<Response>
  <Result>OK</Result>
  <BatchCode>31534</BatchCode>
  <TotalFeeExcludingVAT>0.00</TotalFeeExcludingVAT>
  <CDVResults>
    <Result>
      <Result>Invalid</Result>
      <Message>Branch code not found.</Message>
      <AccountNumber>009071574627</AccountNumber>
    </Result>
  </CDVResults>
</Response>

Validation responses

A validation response occurs when the bank returns the result of the bank account verification. When this happens, a validation response is POSTed back to your server using the CallBackUrl provided in the initial request.

📘

The validation responses are POSTed back to the CallBackUrl whenever a response is returned by the bank. This could occur multiple times as each bank has different response times.

The Response root parameter consists of the following parameters:

ParameterDescription
ResultAlways OK.
BatchCodeThe unique code for the batch that the validations belong to.

The BanvResults 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.

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 validation response

<Response>
  <Result>OK</Result>
  <BatchCode>34477</BatchCode>
  <BanvResults>
    <Result>
      <AccountNumber>123456789101</AccountNumber>
      <IDNumber>5511255173005</IDNumber>
      <Initials>EX</Initials>
      <Name>Example Name</Name>
      <Reference>5621-123456789101</Reference>
      <Flags>YYNNYYYY</Flags>
      <Result>
        A/c exists, ID matches, Inits don't match, Name doesn't match, A/c open, accepts Dr, accepts Cr & open more than 3 months
      </Result>
    </Result>
  </BanvResults>
</Response>