Debit orders

Overview

A debit order request submits data for a debit order batch. After a debit order batch is submitted, a CDV check is performed on the account details provided and any accounts failing that check are included in the response. Any accounts that pass the CDV check are processed.

If an account is rejected by a bank, usually because it has been closed, an unpaids response is
created and POSTed 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 relating to the debit order batch, the DebitOrders section is a collection of account details to be used as the destination for the debit orders, and the Totals section is used to verify that the information being sent is complete and correct.

Header

A debit order 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
ServiceAlways DebitOrder.Required
ServiceTypeAlways 2Day.Required
DueDateThe date the batch should be submitted to the bank for processing.Required
CallBackUrlThe callback URL to be used to send back unpaids.Required
ReferenceThe reference used to identify the batch for reporting.Required
UniqueIdUsed to prevent duplicate requests.Optional

DebitOrders

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

ParameterDescriptionCondition
InitialsThe account holder's initials.Optional
FirstNamesThe account holder's first names.Required
SurnameThe account holder's surname.Required
BranchCodeThe branch code of the account to be debited.Required
AccountNumberThe account number to be debited.Required
FileAmountThe amount to be debited.Required
AmountMultiplier1 if the FileAmount is specified in rands, otherwise 100 if
the FileAmount is specified in cents.
Required
CustomerCodeThe customer code used to identify the debit order in your system.Optional
ReferenceThe reference that appears on the recipient’s bank statement.Required

Totals

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

ParameterDescriptionCondition
RecordsThe total number of debit order records being submitted.Required
AmountThe total value of the debit order records being submitted.Required
BranchHashThe sum of all the branch codes for the debit order records.Required
AccountHashThe sum of all the account numbers for the debit order records.Required

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 is returned with an extra parameter called BatchValueSubmitted which contains the total value of the batch submitted (less any accounts that failed the CDV check).

The results of the CDV check are returned as a CDVResults parameter with a collection of Result
parameters outlining the reasons for the accounts rejection. The Result section consists of the
following parameters:

ParameterDescription
ResultThe result of the CDV check. Always Invalid for a failed account.
MessageThe reason for the rejection.
AccountNumberThe account number that failed the CDV test.

📘

If any of the accounts pass the CDV check, the batch is accepted 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 many reasons, such as the account being closed. When this happens, an unpaid response is POSTed back to your server using the CallBackUrl provided in the initial request. All response data is submitted 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 is submitted.

The Response root parameter consists of the following parameters:

ParameterDescription
ResultAlways OK.
BatchCodeThe unique code for the batch that the unpaids belong to.
DebitOrderResultsThe collection of Results parameters with more information about each unpaid.

The DebitOrderResults section consists of the following parameters:

ParameterDescription
FirstNameThe account holder's first name.
SurnameThe account holder's surname.
BranchCodeThe branch code of the account to be debited.
AccountNumberThe account number to be debited.
CustomerCodeThe customer code used to identify the debit order in your system.
ReferenceThe reference that would have appeared on the recipient’s bank statement.
ResultThe result status. Always Rejected for an unpaid.
ResultMessageThe reason for the unpaid.

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>