Overview

A payments request submits data for a payments batch, which can be for creditors, salaries, or wages. After submitting a payment batch, the API performs a CDV check on the provided account details and the response includes any accounts that fail the check. Processing continues for any 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. The API submits all response data as form data in a POST action, that is application/x-www-form-urlencoded with the key response.

Request URL

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

Request structure

A payments request consists of three separate sections with a root parameter called APIPaymentsRequest. The Header section contains information on the payments batch, the Payments section is a collection of account details that you must use as the destination for the payments, and the Totals section verifies that the information sent is complete and correct.

Header

A payments 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`	The code of the service. See below for the service codes.	Required
`ServiceType`	The payment service type. See below for the service types.	Required
`DueDate`	The date to submit the batch to the bank for processing.	Required
`BankAccount`	The bank account used to deposit the funds. Used to display the Peach Payments account details for your bank account.	Optional
`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

Payment service codes

The following service codes are available for payments:

Wages: For wage payments.
Salaries: For salary payments.
Creditors: For creditor payments.

Payment service types

The following service types are available for payments:

1Day: For 1-day payments.
SDV: For SDV payments.
RTC: For real-time payments.

Payments

A payments request has a single Payments section with multiple FileContents sections with the following parameters:

Parameter	Description	Condition
`Initials`	The payment recipient's initials.	Optional
`FirstNames`	The payment recipient's first names.	Required
`Surname`	The payment recipient's surname or company name.	Required
`BranchCode`	The branch code of the account where you're depositing the payment.	Required
`AccountNumber`	The account number where you're depositing the payment.	Required
`FileAmount`	The deposit amount.	Required
`AmountMultiplier`	`1` if the `FileAmount` is in rands, otherwise `100` if the `FileAmount` is in cents.	Required
`AccountType`	The account type where the funds will be deposited. Leave it blank or use `0` if the account type isn't known. `0` – `6` are accepted.	Optional
`CustomerCode`	The customer code used to identify the payment in your system.	Optional
`Reference`	The reference that appears on the recipient's bank statement.	Required

Totals

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

Parameter	Description	Condition
`Records`	The total number of payment records you're submitting.	Required
`Amount`	The total value of the payment records you're submitting.	Required
`BranchHash`	The sum of all the branch codes for the payment records.	Required
`AccountHash`	The sum of all the account numbers for the payment records.	Required

Example request

<APIPaymentsRequest>
 <Header>
  <PsVer>2.0.1</PsVer>
  <Client>ZER001</Client>
  <DueDate>20200625</DueDate>
  <Service>Creditors</Service>
  <ServiceType>1day</ServiceType>
  <Reference>Example Batch</Reference>
  <CallBackUrl>https://example.com/Callback</CallBackUrl>
 </Header>
 <Payments>
  <FileContents>
   <Initials>EX</Initials>
   <FirstNames>Example</FirstNames>
   <Surname>Recipient</Surname>
   <BranchCode>632009</BranchCode>
   <AccountNumber>123456789</AccountNumber>
   <FileAmount>549.01</FileAmount>
   <AccountType>0</AccountType>
   <AmountMultiplier>1</AmountMultiplier>
   <CustomerCode>EXA9292</CustomerCode>
   <Reference>Example Reference</Reference>
  </FileContents>
 </Payments>
 <Totals>
  <Records>1</Records>
  <Amount>549.01</Amount>
  <BranchHash>632009</BranchHash>
  <AccountHash>123456789</AccountHash>
 </Totals>
</APIPaymentsRequest>

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).

If any of the payments FileContents records failed the CDV check, the API returns them as a CDVResults parameter with a collection of Result parameters describing the rejection reasons. 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>285902</BatchCode>
 <BatchValueSubmitted>549.01</BatchValueSubmitted>
 <TotalFeeExcludingVAT>2.00</TotalFeeExcludingVAT>
 <CDVResults>
  <Result>
   <AccountNumber>123456789</AccountNumber>
   <BranchCode>632009</BranchCode>
   <CustomerCode>EXA9292</CustomerCode>
   <Reference>Example Reference</Reference>
   <Result>Valid</Result>
  </Result>
 </CDVResults>
</Response>

Unpaids

An unpaid occurs when the bank rejects a payment. This can happen for different reasons, such as the closure of the recipient's account. When this happens, the API POSTs an unpaid response back to your server using the CallBackUrl provided in the initial request.

🚧
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.
`PaymentResults`	The collection of `Results` parameters with more information about each unpaid.

The PaymentResults section consists of the following parameters:

Parameter	Description
`FirstName`	The payment recipient's first name.
`Surname`	The payment recipient's surname.
`BranchCode`	The branch code of the account where you're depositing the payment.
`AccountNumber`	The account number where you're depositing the payment.
`CustomerCode`	The customer code used to identify the payment 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>30104</BatchCode>
 <PaymentResults>
  <Result>
   <AccountNumber>123456789</AccountNumber>
   <BranchCode>632005</BranchCode>
   <FirstName>Example</FirstName>
   <Surname>Callback</Surname>
   <Reference>SALARY</Reference>
   <CustomerCode>000001</CustomerCode>
   <Result>Rejected</Result>
   <ResultMessage>ACCOUNT CLOSED</ResultMessage>
  </Result>
 </PaymentResults>
</Response>

Postman collection

See the Peach Payments Postman collection for sample calls.