Overview

A debit order request submits data for a debit order batch. After submitting a debit order batch, the API performs a CDV check on the account details provided and the response includes any accounts that fail the check. Processing continues for accounts that pass the CDV check.

If a bank rejects an account (often because of account closure), the API creates an unpaids response and POSTs it back to the callback URL provided.

Request URL

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

Request structure

A debit order request consists of three separate sections with a root parameter called APIDebitOrdersRequest. The Header section contains information on the debit order batch, the DebitOrders section is a collection of account details that must form the destination for the debit orders, and the Totals section verifies that the information sent is complete and correct.

Header

A debit order request has a single Header section with the following parameters:

DebitOrders

A debit order request has a single DebitOrders section with multiple FileContents sections with the following parameters:

Totals

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

Example request

<APIDebitOrdersRequest>
  <Header>
    <PsVer>2.0.1</PsVer>
    <Client>ZER001</Client>
    <DueDate> 20120918</DueDate>
    <Service>DebitOrder</Service>
    <ServiceType>2day</ServiceType>
    <Reference>Debit Order API Example</Reference>
    <CallBackUrl>http://example.com/APIResponse</CallBackUrl>
  </Header>
  <DebitOrders>
    <FileContents>
      <Initials>CD</Initials>
      <FirstNames>Name 2</FirstNames>
      <Surname>Surname 2</Surname>
      <BranchCode>632005</BranchCode>
      <AccountNumber>123456789</AccountNumber>
      <FileAmount>12569</FileAmount>
      <CustomerCode>ZERO01</CustomerCode>
      <AmountMultiplier>0.01</AmountMultiplier>
      <Reference>Example D/O API 2</Reference>
    </FileContents>
  </DebitOrders>
  <Totals>
    <Records>1</Records>
    <Amount>125.69</Amount>
    <BranchHash>632005</BranchHash>
    <AccountHash>123456789</AccountHash>
  </Totals>
</APIDebitOrdersRequest>

Response structure

The standard response structure includes an extra parameter called BatchValueSubmitted which contains the total value of the batch submitted (less any accounts that failed the CDV check).

The CDV check returns results as a CDVResults parameter with a collection of Result parameters describing the rejections. The Result section consists of the following parameters:

📘

If any of the accounts pass the CDV check, the bank accepts the batch for processing.

Example response

<Response>
  <Result>OK</Result>
  <BatchCode>119146</BatchCode>
  <BatchValueSubmitted>125.69</BatchValueSubmitted>
  <TotalFeeExcludingVAT>0.00</TotalFeeExcludingVAT>
  <CDVResults>
    <Result>
      <Result>Invalid</Result>
      <Message>Branch code not found.</Message>
      <AccountNumber>12345689</AccountNumber>
      <BranchCode>632005</BranchCode>
    </Result>
    <Result>
      <Result>Invalid</Result>
      <Message>Account number is too long (appears to be a credit card).</Message>
      <AccountNumber>7912172416078</AccountNumber>
      <BranchCode>632005</BranchCode>
    </Result>
    <Result>
      <Result>Valid</Result>
      <Message>123456789</Message>
      <AccountNumber>7912172416078</AccountNumber>
      <BranchCode>632005</BranchCode>
    </Result>     
  </CDVResults>
</Response>

Unpaids

An unpaid occurs when the bank rejects a debit order. This can happen for different reasons, such as account closure. When this happens, the API POSTs an unpaid response back to your server using the CallBackUrl provided in the initial request. The API submits all response data as form data in a POST action, that is application/x-www-form-urlencoded with the key response.

🚧

The unpaid responses can continue for several days after the batch submission.

The Response root parameter consists of the following parameters:

The DebitOrderResults section consists of the following parameters:

Example unpaids

<Response>
  <Result>OK</Result>
  <BatchCode>119138</BatchCode>
  <DebitOrderResults>
    <Result>
      <AccountNumber>123456789</AccountNumber>
      <BranchCode>632005</BranchCode>
      <FirstName>Name 2</FirstName>
      <Surname>Surname 2</Surname>
      <Reference>Test D/O API 2</Reference>
      <CustomerCode>ZER001</CustomerCode>
      <Result>Rejected</Result>
      <ResultMessage>AUTHORISATION CANCELLED</ResultMessage>
    </Result>
  </DebitOrderResults>
</Response>