Introduction

Peach Payments offers South African merchants multiple financial services, including:

• Payouts: Batch EFT payments
• Bank account verification (BANV): Confirm that bank accounts are valid
• Real-time bank account verification (BANVR): Confirm, in real-time, that bank accounts are valid
• Check digit verification (CDV): Verify bank account numbers against bank-supplied algorithms to determine if the account numbers fall in a valid range for that bank
• Beneficiaries: Securely manage beneficiary accounts

Payouts

Peach Payments enables South African businesses to make batch EFT payments, for example, to pay suppliers, employees, partners, or customers.

Use payouts in the following ways:

• By manually uploading a CSV file using the peachpay.co.za portal.
• By integrating with the API.

Both methods require that you either:

• Keep funds in your account that Peach Payments debits on each batch request.
• Transfer the total amount that you want paid.

📘

Payouts supports same-day settlements into all banks in South Africa.

To gain access to the peachpay.co.za portal and your API credentials, contact support.

Bank account verification (BANV)

A BANV request submits data to verify a batch of account numbers against the information provided. After submitting a batch, the API performs a CDV check on the provided account details and the response includes any accounts failing that check. Processing continues for any accounts that pass the CDV check.

Real-time bank account verification (BANVR)

A BANVR request submits data to verify a single account number against the information provided. Real-time account verification has a guaranteed response time of 60 seconds from the bank. If a response is not received in 60 seconds, no result occurs. Because the response occurs in real-time, a callback URL is not supplied as there is no callback.

Check digit verification (CDV)

A CDV request submits data to verify a batch of account numbers against a bank-supplied algorithm to determine if the account numbers fall in a valid range for that bank.

Beneficiaries

The Peach Payments beneficiary API enables developers to securely manage beneficiary accounts.

API usage

Getting started

To use the APIs, you must have an API key. Include your API key in every request to identify your application. If you provide the wrong key or no key, you cannot access the APIs. Append your API key to the request URL as a query string parameter, for example, <https://www.peachpay.co.za/API/Verification?key=6281ac86e87f485aa78bd4b90e14cf2c> where 6281ac86e87f485aa78bd4b90e14cf2c is your unique API key.

Submit all request and response data as form data in a POST action, that is application/x-www-form-urlencoded with the response key.

To assist in visualising the request, see the following screenshot of the values in Postman:

Response formats and structures

Successful request

The response is in structured XML format and always has the following basic structure:

<Response>
 <Result>OK</Result>
 <BatchCode>285906</BatchCode>
 <TotalFeeExcludingVAT>1.75</TotalFeeExcludingVAT>
</Response>

• The Result element's value is always OK if no errors occur.
• The BatchCode element's value displays the batch code for that transaction. The batch code is unique and all responses include it so that you can determine which batch the response is for.
• The TotalFeeExcludingVAT element's value returns the fees charged by Peach Payments for that batch.
• Different services might return other elements.

Dates are always in the yyyyMMdd format, for example, 20120214 is 14 February 2012.

If you include a unique ID value, the response includes it as well.

Unsuccessful request

<Response>
 <Result>Error</Result>
 <ResultMessage>Your key is invalid</ResultMessage>
</Response>

If a request is unsuccessful, the Result element's value is always Error. The ResultMessage value describes why the error occurred.

Duplicate checking

Peach Payments recommends that all requests include a UniqueId field in the request header. Save it with the batch as a unique identifier. The API rejects any duplicate requests that arrive with the same UniqueId. The result includes the original batch code.

<Response>
 <Result>Error</Result>
 <ResultMessage>This batch has the same unique Id as another batch and is rejected as a duplicate</ResultMessage>
 <BatchCode>285907</BatchCode>
</Response>

Using tokens in place of account details

Each beneficiary record includes an API token as a shortcut for filling in the account details for that transaction. If the token field is present in the FileContents section, the API ignores all other fields except FileAmount and AmountMultiplier.

The token matches a beneficiary record for the client code specified in the request and the beneficiary record retrieves the relevant information.

For security reasons, CDV results do not include the account number or branch code in the API response but do include the customer code and token so that you can match it to the original transaction.

<Response>
 <Result>OK</Result>
 <BatchCode>285909</BatchCode>
 <TotalFeeExcludingVAT>1.75</TotalFeeExcludingVAT>
 <CDVResults>
 <Result>
 <CustomerCode>EXA9292</CustomerCode>
 <Result>Valid</Result>
 <Token>377089C6C48CB38ACB4134F50D84004D3657CB03</Token>
 </Result>
 </CDVResults>
</Response>

A CDV error occurs including the token value if there is no matching beneficiary record.

<Response>
 <Result>OK</Result>
 <BatchCode>285926</BatchCode>
 <BatchValueSubmitted>549.01</BatchValueSubmitted>
 <CDVResults>
 <Result>
 <CustomerCode></CustomerCode>
 <Message>Token can not be matched to beneficiary. Ensure the beneficiary is active and linked to this service.</Message>
 <Result>Invalid</Result>
 <Token>377089C6C48CB38ACB4134F50D84004D3657CB01</Token>
 </Result>
 </CDVResults>
</Response>

External links

Use external links to reference an object or page that is not part of the Peach Payments secure web interface. For example, you can link to the original invoice for a payment for reports. All requests can include an optional ExternalLinks section for each account (FileContents) parameter.

The authorisation page of the secure web interface displays external links.

Structure

An ExternalLink section consists of the following elements:

The ExternalLinks section can include multiple ExternalLink sections.

<APIPaymentsRequest>
 <Header>
  <PsVer>2.0.1</PsVer>
  <Client>ZER001</Client>
  <DueDate>20201125</DueDate>
  <Service>Wages</Service>
  <ServiceType>1day</ServiceType>
  <Reference>Example Batch</Reference>
 </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>
   <ExternalLinks>
    <ExternalLink>
     <Label>Invoice 12345</Label>
     <URL>https://example.com/View/12345</URL>
     </ExternalLink>
    </ExternalLinks>
   </FileContents>
 </Payments>
 <Totals>
  <Records>1</Records>
  <Amount>549.01</Amount>
  <BranchHash>632009</BranchHash>
  <AccountHash>123456789</AccountHash>
 </Totals>
</APIPaymentsRequest>

Parameter data types and lengths

The table below lists the parameter data types and lengths.