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:

ParameterDescriptionCondition
PsVerThe version of the Peach Payments file format. 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 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:

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 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 includes 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 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.

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:

ParameterDescription
ResultThe result of the CDV check. Always Invalid for a failed account.
MessageThe rejection reason.
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 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 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>

Postman collection

See the Peach Payments Postman collection for sample calls.

Run in Postman