Introduction

Peach Payments offers South African merchants a number of 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 within a valid range for that bank
  • Debit orders: Collect funds from your customers
  • 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.

Payouts can be used in two ways:

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

Both methods require that you either:

  • Maintain funds in your account that Peach Payments debits on each batch request.
  • Transfer the total amount that needs to be paid out.

📘

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

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

Bank account verification (BANV)

A BANV request submits data to verify a batch of account numbers against the information provided. After a 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.

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 is returned. Due to the real-time response, no callback URL is supplied as no callback is sent.

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 within a valid range for that bank.

Debit orders

A debit orders 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.

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. Your API key must be included in every request to identify your application. If no key or an incorrect key is provided, you cannot access the APIs. Your API key must be appended 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.

All request and response data are submitted 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:

API values in Postman.API values in Postman.

API 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 are encountered.
  • The BatchCode element’s value displays the batch code for that transaction. The batch code is unique and is returned with all responses 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.
  • Other elements may be returned depending on the service.

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

If a unique ID value is included, it is returned in the response 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 displays the reason for the error.

Duplicate checking

We recommend that all requests include a UniqueId field in the request header. This is saved with the batch as a unique identifier. If a duplicate request arrives with the same UniqueId, it is rejected. The original batch code is included in the result.

<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 that can be used as a shortcut for filling in the account details for that transaction. If the token field is present in the FileContents section, all other fields except FileAmount and AmountMultiplier are ignored and can be excluded.

The token is matched to a beneficiary record for the client code specified in the request and the relevant information is filled in from the beneficiary record.

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 is returned with the token value if no matching beneficiary record is found.

<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

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

External links are displayed on the authorisation page of the secure web interface and are being rolled out to other reports.

Structure

An ExternalLink section consists of the following elements:

ParameterDescriptionCondition
LabelA description of the link; displayed next to each link when reporting.Required
URLThe URL of the link.Required

Multiple ExternalLink sections can be included in the ExternalLinks section.

<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 and lengths.

Parameter

Description

Data type

Maximum length

Initials

The payment recipient's initials.

Alphanumeric

50

FirstNames

The payment recipient's first names.

Alphanumeric

250

Surname

The payment recipient's surname.

Alphanumeric

250

ContactNumber

The contact number to be used for the search.

Alphanumeric

255

IdNumber

The ID number of the person linked to the contact number.

Numeric

100

BranchCode

The branch code of the account where the payment is being deposited.

Numeric

10

AccountNumber

The account number where the payment is being deposited.

Numeric

15

FileAmount

The deposit amount.

Decimal

18 characters and 2 decimals

AmountMultiplier

1 if the FileAmount is specified in rands, 100 if the FileAmount is specified in cents.

Numeric

3

AccountType

The type of account where the funds are being deposited. Can be left blank or set to 0 if you don’t know. 06 can be used.

  • Unknown = 0
  • Current/Cheque = 1
  • Savings = 2
  • Transmission = 3
  • Bond = 4
  • Subscription share = 6

Numeric

1

CustomerCode

The customer code used to identify the payment in your system.

Alphanumeric

50

Reference

The reference on the recipient’s bank statement.

Alphanumeric

20


Did this page help you?