Peach Payments offers South African merchants multiple financial services, including:
- Payouts: Batch EFT payments
- Debit orders: Collect funds from your customers
- 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
- Beneficiaries: Securely manage beneficiary accounts
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:
Both methods require that you either:
- Maintain 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.
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.
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. Since the response occurs in real-time, a callback URL is not supplied as there is no callback.
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.
A debit orders request submits data for a debit order batch. After submitting a debit order 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.
The Peach Payments beneficiary API enables developers to securely manage beneficiary accounts.
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 incorrect key or no key, you cannot access the APIs. Append your API key to the request URL as a query string parameter, for example,
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
To assist in visualising the request, see the following screenshot of the values in Postman:
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>
Resultelement's value is always
OKif no errors occur.
BatchCodeelement'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.
TotalFeeExcludingVATelement'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.
<Response> <Result>Error</Result> <ResultMessage>Your key is invalid</ResultMessage> </Response>
If a request is unsuccessful, the
Result element's value is always
ResultMessage value describes why the error occurred.
We recommend 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>
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
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>
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 (
The authorisation page of the secure web interface displays external links.
ExternalLink section consists of the following elements:
|A description of the link; displayed next to each link when reporting.||Required|
|The URL of the link.||Required|
ExternalLinks section can include multiple
<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>
The table below lists the parameter data types and lengths.
|Parameter||Description||Data type||Maximum length|
|The payment recipient's initials.||Alphanumeric||50|
|The payment recipient's first names.||Alphanumeric||250|
|The payment recipient's surname.||Alphanumeric||250|
|Use this contact number for the search.||Alphanumeric||255|
|The ID number of the person linked to the contact number.||Numeric||100|
|The branch code of the account where the payment is being deposited.||Numeric||10|
|The account number where the payment is being deposited.||Numeric||15|
|The deposit amount.||Decimal||18 characters and 2 decimals|
|The account type where the funds are being deposited. Leave blank or set to |
- Unknown =
- Current/Cheque =
- Savings =
- Transmission =
- Bond =
- Subscription share =
|The customer code used to identify the payment in your system.||Alphanumeric||50|
|The reference on the recipient's bank statement.||Alphanumeric||20|
Updated 4 days ago