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:

Parameter	Description	Condition
`PsVer`	The version of the Peach Payments file format. 2.0.1.	Required
`Client`	Your unique client code.	Required
`Reference`	The batch reference. Allows you to identify the batch in the reports and the verification responses.	Required
`UniqueId`	Used to prevent duplicate requests.	Optional
`CallBackUrl`	If 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:

Parameter	Description	Condition
`Initials`	The account holder's initials.	Optional
`Name`	The account holder's (or company's) name.	Required
`IdNumber`	The account holder's ID, passport, or company registration number.	Optional
`AccountNumber`	The account number for verification.	Required
`BranchCode`	The branch code of the account number.	Required
`Reference`	A transaction reference. Used to uniquely identify a verification record.	Optional

Totals

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

Parameter	Description	Condition
`Records`	The total number of BANVR records submitted.	Required
`BranchHash`	The sum of all the branch codes for the BANVR record.	Required
`AccountHash`	The 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:

Parameter	Description
`Result`	Always `OK`.
`BatchCode`	The unique code for the batch that the validation belongs to.

The BanvRealTimeResult section consists of the following parameters:

Parameter	Description
`AccountNumber`	The account number you are verifying.
`IDNumber`	The account holder's ID, passport, or company registration number.
`Initials`	The account holder's initials.
`Name`	The account holder's or company's name.
`Reference`	The batch reference. Allows you to identify the batch in the reports.
`Flags`	`Y`, `N`, and blank characters mean a corresponding result. See below for details.
`Result`	The 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:

Parameter	Description
`Result`	The result of the CDV check. Always `Invalid` for a failed account.
`Message`	The rejection reason.
`AccountNumber`	The 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:

Account exists
ID number or company registration matches
Initials match (should be blank to match for company)
Surname or company name matches
Account open
Account accepts debits
Account accepts credits
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.