Overview

A payments request submits data relating to a payments batch, which can be for creditors, salaries, or wages. After a payment batch has been 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 continue to be 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. All response data is submitted 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 relating to the payments batch, the Payments section is a collection of account details to be used as the destination for the payments, and the Totals section is used to verify that the information being sent is complete and correct.

Header

A payments 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 of the service being used. See below for the service codes.Required
ServiceTypeThe service type of the payment. See below for the service types.Required
DueDateThe date the batch should be submitted to the bank for processing.Required
BankAccountThe bank account used to deposit the funds. Used to display the Peach Payments account details for your bank account.Optional
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

Payment service codes

The following service codes are available for payments:

  • Wages: For payments relating to wages.
  • Salaries: For payments relating to salaries.
  • Creditors: For payments relating to creditors.

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:

ParameterDescriptionCondition
InitialsThe payment recipient's initials.Optional
FirstNamesThe payment recipient's first names.Required
SurnameThe payment recipient's surname or company name.Required
BranchCodeThe branch code of the account where the payment is being deposited.Required
AccountNumberThe account number where the payment is being deposited.Required
FileAmountThe deposit amount.Required
AmountMultiplier1 if the FileAmount is specified in rands, otherwise 100 if
the FileAmount is specified in cents.
Required
AccountTypeThe type of account where the funds will be deposited. Can
be left blank or 0 can be used if the account type isn't known. Only 06 can be used.
Optional
CustomerCodeThe customer code used to identify the payment in your system.Optional
ReferenceThe reference that appears on the recipient’s bank statement.Required

Totals

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

ParameterDescriptionCondition
RecordsThe total number of payment records being submitted.Required
AmountThe total value of the payment records being submitted.Required
BranchHashThe sum of all the branch codes for the payment records.Required
AccountHashThe 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 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).

If any of the payments FileContents records failed the CDV check, they are returned as a CDVResults parameter with a collection of Result parameters outlining the reasons for the account rejections. 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>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 many reasons, such as the recipient's account being closed. When this happens, an unpaid response is POSTed back to your server using the CallBackUrl provided in the initial request.

🚧

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.
PaymentResultsThe collection of Results parameters with more information about each unpaid.

The PaymentResults section consists of the following parameters:

ParameterDescription
FirstNameThe payment recipient's first name.
SurnameThe payment recipient's surname.
BranchCodeThe branch code of the account where the payment is being deposited.
AccountNumberThe account number where the payment is being deposited.
CustomerCodeThe customer code used to identify the payment 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>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>