Bank account verification (BANV)

Overview

A BANV request submits data to verify a batch of account numbers against the information provided. After submitting a batch, BANV performs a CDV check on the account details provided and the response includes any accounts that fail that check. Processing continues for accounts that pass the CDV check.

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 on the BANV batch, the Records section is a collection of account details for verification, and the Totals section verifies that the information 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. 2.0.1.Required
ClientYour unique client code.Required
ServiceThe code for the service. BANV for bank account verification.Required
ReferenceThe batch reference. Allows you to identify the batch in the reports and the verification responses.Required
CallBackUrlUse this callback URL 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 for verification.Required
BranchCodeThe branch code of the account number.Required
ReferenceA transaction reference. 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 API returns the standard response structure as form data in a POST action, for example, application/x-www-form-urlencoded with the response key.

The API returns any BANV FileContents records that fail the CDV check as a CDVResults parameter with a collection of Result parameters describing the rejection. The Result section consists of the following parameters:

ParameterDescription
ResultThe result of the CDV check. Always Invalid for a failed account.
MessageThe rejection reason.
AccountNumberThe account number that failed the CDV test.

📘

If any of the accounts passed the CDV check, tha bank accepts the batch and continues the verification.

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, the API POSTs a validation response back to your server using the CallBackUrl provided in the initial request.

📘

The API POSTs the validation responses back to the CallBackUrl whenever the bank returns a response. 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 that you are verifying.
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 mean 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 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 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>

Postman collection

See the Peach Payments Postman collection for sample calls.

Run in Postman