Check digit verification (CDV)

Overview

A CDV request submits data to verify a batch of account numbers against a bank-supplied algorithm to determine if the account numbers fall within a valid range for that bank.

Request URL

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

Request structure

A CDV request consists of three separate sections with a root parameter called APICDVRequest. The Header section contains information relating to the CDV 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 CDV 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. CDV for check digit verification.Required
ReferenceThe batch reference. Allows you to identify the batch on the history page of the secure website.Required
UniqueIdUsed to prevent duplicate requests.Optional

Records

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

ParameterDescriptionCondition
AccountNumberThe account number to be verified.Required
BranchCodeThe branch code of the account number to be verified.Required
CustomerCodeThe customer identifier that is returned with the CDV results.Optional

Totals

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

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

Example request

<APICDVRequest>
  <Header>
    <PsVer>2.0.1</PsVer>
    <Client>EXA001</Client>
    <Service>CDV</Service>
    <Reference>TEST CDV</Reference>
  </Header>
  <Records>
    <FileContents>
      <AccountNumber>559071574627</AccountNumber>
      <BranchCode>632005</BranchCode>
    </FileContents>
  </Records>
  <Totals>
    <Records>1</Records>
    <BranchHash>632005</BranchHash>
    <AccountHash>559071574627</AccountHash>
  </Totals>
</APICDVRequest>

Response structure

The standard response structure is returned with a CDVResults parameter containing the validation results.

The Response root parameter has the following parameters:

ParameterDescription
ResultAlways OK.
BatchCodeDeprecated. Empty.
TotalFeeIncludingVatDeprecated. 0.
UniqueIdThe unique ID submitted

The Result section has the following parameters:

ParameterDescription
ResultThe result of the CDV check. Invalid for a failed account.
MessageThe reason for the rejection.
AccountNumberThe account number that failed the CDV test.
BranchCodeThe branch code that was submitted.
ReferenceThe reference that was submitted.

Example valid response

<Response>
  <Result>OK</Result>
  <BatchCode></BatchCode>
  <TotalFeeExcludingVAT>0</TotalFeeExcludingVAT>
  <UniqueId>12345443</UniqueId>
  <CDVResults>
    <Result>
      <Result>Valid</Result>
      <AccountNumber>123456789</AccountNumber>
      <BranchCode>632005</BranchCode>
      <Reference>Example 1</Reference>
    </Result>
  </CDVResults>
</Response>

Example invalid response

<Response>
  <Result>OK</Result>
  <BatchCode></BatchCode>
  <TotalFeeExcludingVAT>0</TotalFeeExcludingVAT>
  <UniqueId>12345443</UniqueId>
  <CDVResults>
    <Result>
      <Result>Invalid</Result>
      <Message>Account number is not valid for ABSA Bank.</Message>
      <AccountNumber>1234567891</AccountNumber>
      <BranchCode>632005</BranchCode>
      <Reference>Example 1</Reference>
    </Result>
  </CDVResults>
</Response>