1. Adding a Beneficiary via API request


Generating a Bearer Token:


First, generate a bearer token required to authenticate the Beneficiary API request:


Example:

curl --location --request POST 'https://api.test.peachpay.co.za/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=XXXXXX' \
--data-urlencode 'password=XXXXXX'

 Note: username and password used on the request above are login credentials for the payout portal (https://test.peachpay.co.za/


Response:

{
    "access_token": "VTMogQ6ygkQ9bTxGWM_EV2lVOE25I1_007SgpJpheBtIa1Kz-kWhx2VwlrhSo74Xs18YQSGgK7w5l_JL4qQFT5H5Tsi0VEa02GuOzY8DwrP3cEY-cGEWgLclW5FQiHqtyfp2zw17YTa1AXGHmlkkF7ZRacFg5EQ_Y4viPbcLFI8BwHOpdHitwPGa2mLYDCCOhEG86E6KLQI202WEaa8zcs17bTLnkOIcDj_b7pevIDWrnY2Sh7NOED1bGtwYlovgcq1VFeD4wlWaveF34-NHBUI132G-E7_yWZbBLWSV86mTRzijeWNL6SokIcp7Y6tyQL8h1o7BwS1D7OjPwcHlhlzXxnyvbq0KuSSDA9y-8daQtFaDJUR1M9A8ztdD7xg6ds12htlM4WeOcMoVabhzTcMTAms",
    "token_type": "bearer",
    "expires_in": 86399
}


Adding a Beneficiary:

Example:

curl --location --request POST 'https://api.test.peachpay.co.za/api/beneficiaries/collections/' \
--header 'Authorization: Bearer DzMsy3xOtfF0mqAij7fWLcieWYTwnxRf5kt0l1br2SQvVGf2tQeaWO4WS2arAz2G5d4A_ifJkHBN0VtsfZIlbGGXMAdOMLXJ65pPATo_v7fNU_Geu2OVzmyQvD5YJBjdXszpYQPX9pkFCrvB55C77ntHnmqPv3NqQ-qXTrg27gIttFEzrHyDt6xasBQZZ8jcEiQNxZ6HFM5tg6_c13smc1SU9vUxA49ZXXcdJlHYx65xrobQkG72ZCbzsr8fRsQ6d1zh4V_w7IHAhb6N4vUqeA0GM0mfNR7NTvzjOtjc-73gtfMm-MEYSyzOFse9v7j4g5Zip8A-c7bds7ojWEgXEz57Yssi6SJjxe3oYP4vonUjvJvY2UhOmk7LDxwscMTtrTfYaV5ho5PCnu4uQZM6253Ostw' \
--header 'Content-Type: application/json' \
--data-raw '
{
            "accountNumber": "123456789",
            "amount": null,
            "branchCode": "632005",
            "clientCode": "PPPEA001",
            "clientName": "Peach Payments Test",
            "customerCode": "1111",
            "id": null,
            "isActive": true,
            "name": "TEST1234590",
            "reference": "123465",
            "scheculeType": 0,
            "serviceCode": "DEBORD"
  }
    '


Service Codes

  • Debit Order : DEBORD
  • Salaries : PPREFTSAL
  • Creditors : PPREFTCRE
  • Wages : PPREFTWAG


Response:

{
    "accountNumber": "123456789",
    "bankName": "",
    "branchCode": "632005",
    "debitDay": null,
    "debitMonth": null,
    "trackingDays": null,
    "accountType": 0,
    "amount": null,
    "clientCode": "PPPEA001",
    "clientName": "Peach Payments Test",
    "customerCode": "1111",
    "endDate": null,
    "id": "251208148090108016041080167090244121000011171177",
    "installments": null,
    "isActive": true,
    "name": "TEST1234590",
    "recurringPeriod": 0,
    "reference": "123465",
    "scheduleType": 0,
    "serviceCode": "DEBORD",
    "startDate": null,
    "tokenHash": "FEF7775775F4C86B8559BF0801E96C9B4B0567F6"
}



2. Submitting Debit Order/Salaries /Wages/Creditors request using a Token

Use the Token Hash from the "add beneficially" response in-place of the account number 


Debit Order request example:

curl --location --request POST 'https://test.peachpay.co.za/API/DebitOrder?key=8a983d37-e56a-4f8e-977c-4f2b0e78766a' \
--header 'key;' \
--form 'request="<APIDebitOrdersRequest> 
<Header> 
<PsVer>2.0.1</PsVer> 
<Client>PEA001</Client> 
<Service>DebitOrder</Service> 
<ServiceType>2Day</ServiceType>
<UniqueId>731876904512</UniqueId> 
<Duedate>20221207</Duedate> 
<Reference>1111</Reference> 
<CallBackUrl></CallBackUrl> 
</Header> 
<DebitOrders> 
<FileContents> 
<FirstNames>John</FirstNames>
<Surname>Doe</Surname>
<Token>FEF7775775F4C86B8559BF0801E96C9B4B0567F6</Token>
<FileAmount>5.00</FileAmount>
<AmountMultiplier>1</AmountMultiplier>
<Reference>7318769045</Reference>
</FileContents> 
</DebitOrders> 
<Totals> 
<Records>1</Records> 
<Amount>5.00</Amount> 
<Token>FEF7775775F4C86B8559BF0801E96C9B4B0567F6</Token>
</Totals> 
</APIDebitOrdersRequest>"' \
--form '=""'


Response:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Response>
    <Result>OK</Result>
    <BatchCode>381404</BatchCode>
    <BatchValueSubmitted>5.00</BatchValueSubmitted>
    <TotalFeeExcludingVAT>1.00</TotalFeeExcludingVAT>
    <UniqueId>731876904512</UniqueId>
    <CDVResults>
        <Result>
            <CustomerCode>1111</CustomerCode>
            <Result>Valid</Result>
            <Token>FEF7775775F4C86B8559BF0801E96C9B4B0567F6</Token>
        </Result>
    </CDVResults>
</Response>



Do the same for Salaries /Wages/Creditors (use the Token instead of Bank Account Number)




More information regarding beneficiaries: https://support.peachpayments.com/a/solutions/articles/47001098761