Debit orders
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:
Parameter | Description | Condition |
---|---|---|
PsVer | The version of the Peach Payments file format. 2.0.1. | Required |
Client | Your unique client code. | Required |
Service | Always DebitOrder . | Required |
ServiceType | Always 2Day . | Required |
DueDate | The date to submit the batch to the bank for processing. | Required |
CallBackUrl | Use this callback URL to send back unpaids. | Required |
Reference | The reference used to identify the batch for reporting. | Required |
UniqueId | Used to prevent duplicate requests. | Optional |
DebitOrders
A debit order request has a single DebitOrders
section with multiple FileContents
sections with the following parameters:
Parameter | Description | Condition |
---|---|---|
Initials | The account holder's initials. | Optional |
FirstNames | The account holder's first names. | Required |
Surname | The account holder's surname. | Required |
BranchCode | The branch code of the account you're debiting. | Required |
AccountNumber | The account number you're debiting. | Required |
FileAmount | The amount you're debiting. | Required |
AmountMultiplier | 1 if the FileAmount is in rands, otherwise 100 if the FileAmount is in cents. | Required |
CustomerCode | The customer code used to identify the debit order in your system. | Optional |
Reference | The reference that appears on the recipient's bank statement. | Required |
Totals
A debit order request has a single Totals
section with the following parameters:
Parameter | Description | Condition |
---|---|---|
Records | The total number of debit order records you're submitting. | Required |
Amount | The total value of the debit order records you're submitting. | Required |
BranchHash | The sum of all the branch codes for the debit order records. | Required |
AccountHash | The 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 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:
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. |
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:
Parameter | Description |
---|---|
Result | Always OK . |
BatchCode | The unique code for the batch that the unpaids belong to. |
DebitOrderResults | The collection of Results parameters with more information about each unpaid. |
The DebitOrderResults
section consists of the following parameters:
Parameter | Description |
---|---|
FirstName | The account holder's first name. |
Surname | The account holder's surname. |
BranchCode | The branch code of the account you're debiting. |
AccountNumber | The account number you're debiting. |
CustomerCode | The customer code used to identify the debit order in your system. |
Reference | The reference that would have appeared on the recipient's bank statement. |
Result | The result status. Always Rejected for an unpaid. |
ResultMessage | The unpaid reason. |
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>
Postman collection
See the Peach Payments Postman collection for sample calls.
Updated 2 months ago