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:

Records

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

Totals

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

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://example.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:

📘

If any of the accounts passed the CDV check, the 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:

The BanvResults section consists of the following parameters:

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.