Beneficiaries

Overview

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

Endpoints

  • Live: https://api.peachpay.co.za/
  • Test: https://api.test.peachpay.co.za/

Authentication

The API uses a bearer token to authenticate all requests. To obtain a token, submit a POST (x-www-form-urlencoded) request to <https://api.peachpay.co.za/token> with the following key-value pairs:

ParameterDescriptionCondition
UsernameYour peachpay.co.za portal username.Required
PasswordYour peachpay.co.za portal password.Required
Grant_typepassword.Required

Code snippets

var client = new RestClient("http://api.peachpay.co.za/token");

var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=password&userName=<your_username>&password=<your_password>", ParameterType.RequestBody);

IRestResponse response = client.Execute(request);
curl --location --request POST 'https://api.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'

If the request is successful, an access token is returned in a JSON response. If the request fails, an error response is returned.

{
  "access_token": "dVIBa8aOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0-CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiw0c",
  "token_type": "bearer", 
  "expires_in": 86400
}
{
  "error": "invalid_grant",
  "error_description": "The user name or password is incorrect."
}

Authorisation

All requests must be submitted with an Authorization header to be processed. The header value must be Bearer {{access_token}}, with the {{access_token}} being the access token received in your authentication request.

An example header is:
Bearer WKoIhYPafaHu2LmZLMtdac0isRLCnC3PkVnwD4LQW3bL8hAsWGQn3k9Q2-EONYHaDiLfcdPQaoeWLuEHpjr6WPTIlhoQLoYJkf61cYV4IIzY8MMyCxTCLhOBA4jCkREuKSJoaVuF69khnlMEFesoYvE70fXlIUnHGxYWl5tyXw2I_9g5O-AnmJ6PpzpvAx8jSwexoh_ttjRlj7nr5F54RoGO9BpICtmN-QM1JwImCP5J2LDHhorXlZsB2KxVdaucKvWbOHe3bapu9NsFDCyJYjxgfwVIX_ARLUY1Hm62_QsZCpoyQ_u5Hg32uUmeetH1XuZdOYIRG6rRXXPe7r4v0uxQP_8v0pDKroGQj5IcPz7p90LuZEymtzwhhtCCW4vpV_9gKrFbeiwOjCIww

Search for payment beneficiaries

Overview

The search function enables an API client to search the available beneficiaries. If no search criteria are supplied, all beneficiaries are displayed.

Request URL

The API supports GET requests with a query string to specify the request parameters: GET <https://api.peachpay.co.za/api/beneficiaries/payments>

Request parameters

The following request parameters can be specified on the request query string.

Headers

Authorization: Bearer {{bearer_token}}

ParameterDescriptionConditionDefault value
ClientThe client code you are searching for, as supplied by Peach Payments.Required
ServiceThe service code you are searching for.Required
QueryLiteral text or phrase that can be contained in beneficiary fields. The fields matched include Account Number, Customer Code, Branch Code, Branch Name, Beneficiary Name, and Reference.Optional
PageThe page number to retrieve in a set of results.Optional1
PageSizeThe maximum number of results per page.Optional20

Code snippets

var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/payments/?client=PSZER001&service=PPREFTWAG");
client.Timeout = -1;

var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer 1DjCRegovjauuoVU5nAsrlCLFTpYTx2C_ScWeIel1FgO9WzWPcL4QkwtwM3Yfds5Nm1oeF4oA4w8RBIjGANWW_yP6vzZuWuqdvCdY1nrUqv1AI2C0DT8HlAwqScjM_20leB67hz6HV6nYugirPPaE_Bh39UbBmxpcOhFi6avDGhL6yJaT3W2jqooyItJ5ueHWcKhVIjAjHBYn9_CdHKCIMBtcp9GMAfMxV308VYkf4VrCwfu46RPjl09334ElLQl5-r3Za28OeNmdGWmZB4C6ocvZqqzIMbbafj_7zkdwfdd8LQMWwUIAt5N3Jwk7kjLI3t8tIsoiqiNsLP_n5RLtq_BrWuyBKW2RTu0Khb5JU2ubSzOahZB8nHnmUPIEV6P8HxEbJCQmIzTi0xpH0chGm8SnU");

IRestResponse response = client.Execute(request);
curl --location --request GET 'https://api.peachpay.co.za/api/beneficiaries/payments/?client=PSZER001&service=PPREFTWAG' \
--header 'Authorization: Bearer 1DjCRegovjauuoVU5nAsrlCLFTpYTx2C_ScWeIel1FgO9WzWPcL4QkwtwM3Yfds5Nm1oeF4oA4w8RBIjGANWW_yP6vzZuWuqdvCdY1nrUqv1AI2C0DT8HlAwqScjM_20leB67hz6HV6nYugirPPaE_Bh39UbBmxpcOhFi6avDGhL6yJaT3W2jqooyItJ5ueHWcKhVIjAjHBYn9_CdHKCIMBtcp9GMAfMxV308VYkf4VrCwfu46RPjl09334ElLQl5-r3Za28OeNmdGWmZB4C6ocvZqqzIMbbafj_7zkdwfdd8LQMWwUIAt5N3Jwk7kjLI3t8tIsoiqiNsLP_n5RLtq_BrWuyBKW2RTu0Khb5JU2ubSzOahZB8nHnmUPIEV6P8HxEbJCQmIzTi0xpH0chGm8SnU'

Response objects

The API returns a JSON-serialized response containing the matched records for the search request:

{
 "pageData": {
  "nextPageNumber": null,
  "pageCount": 1,
  "pageNumber": 1, 
  "pages": [], 
  "pageSize": 20,
  "previousPageNumber": null,
  "showNextPage": false, 
  "showPreviousPage": false, 
  "totalResults": 15
  },
 "results": [
   {
  "approvedBeneficiaryCode": null,
    "accountType": 0,
  "amount": 100.00,
  "clientCode": "PPPEA001",
  "clientName": "Peach Payments Test",
  "customerCode": "2006",
  "endDate": "2022-06-01T00:00:00",
  "id": "236254171067071241144027185019132202029072112228",
  "installments": 2,
  "isActive": true,
  "name": "2006",
  "recurringPeriod": 3,
  "reference": "SmartWill",
  "scheduleType": 1,
  "serviceCode": "DEBORD",
  "startDate": "2020-06-01T00:00:00",
  "tokenHash": "A9DB35243F9AECEF73A9205DB07D417539A93AB8"
   }
  ]
}

This object contains the following parameters:

ParameterDescriptionFormat
PageDataContains the paging information as an object.Object
ResultsThe data parameter containing an array of search results.Array

The results object contains the following parameters:

ParameterDescriptionFormat
ApprovedBeneficiaryCodeThe code for authorised beneficiaries, for example, SARS, MultiChoice, and so on.String
AccountTypeThe account type.Integer
AmountThe amount to be paid.Decimal
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client's name.String
CustomerCodeThe customer code.String
EndDateThe end date.Date
IdThe unique beneficiary identifier.String
InstallmentsThe number of installments.Integer
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary's name.String
RecurringPeriodThe recurring period type.Integer
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
StartDateThe start date.Date
TokenHashA generated token for future use.String

Manage payment beneficiaries

Overview

The management of beneficiaries consists of two parts, allowing for the retrieval of a beneficiary record by identifier, or to update a beneficiary by identifier. This endpoint also allows you to add new beneficiaries.

Retrieve beneficiaries

Request URL

The API supports GET requests with a query string to specify the beneficiary identifier:

  • Using query string parameter: GET <https://api.peachpay.co.za/api/beneficiaries/payments/get?entityKey={{beneficiary_identifier}}>
  • Using route parameter: GET <https://api.peachpay.co.za/api/beneficiaries/payments/{{beneficiary_identifier}}>

Request parameters

The API allows you to retrieve a specific beneficiary record using the beneficiary identifier.

Headers

Authorization: Bearer {{bearer_token}}

ParameterDescriptionCondition
EntityKeyThis is the beneficiary identifier as returned in the id field of the beneficiary object.Required

Code snippets

var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/payments/get?entityKey=<beneficiary ID>");
client.Timeout = -1;

var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer 3kv7sD1y0jOZ6Vsdv7cQ1_vHdK0nu2zEyr3knH0CSd0uFl0C6eD54sRGMlQuvAgwl3hVZoilEr6mAN5NsDGKwRMxFLf2UTPS1bC7Czkx3pL4fRT9lCvEOKCAD2uiheAmrLGYNC11p92JmgDbdmx2BbKJNV2I1YSPt8vbDacgq5ztIKsNO14TkimnfcRX3y6PBklwi9orsUx3CWODJIiWOM1ozv9YgTp1F1fSqUzLAEzJBUyMQI8yCF-rDmzCwXxVeIrW--7QUK10Qexj_yOfZ1P_PFwLYoQdTmCZofiDxk5btA_UrR81--t0yztyrsMdLeCQYXWBtEjA3_SvXlnpptFpj-iR9BUFwtOMvmbJOnKkHI0-AhghAm5iJipjgPCLM-8M0nmu5hxOPpIXyzAYQHMHY");

IRestResponse response = client.Execute(request);
curl --location --request GET 'https://api.peachpay.co.za/api/beneficiaries/payments/get?entityKey=<beneficiary ID>' \
--header 'Authorization: Bearer 3kv7sD1y0jOZ6Vsdv7cQ1_vHdK0nu2zEyr3knH0CSd0uFl0C6eD54sRGMlQuvAgwl3hVZoilEr6mAN5NsDGKwRMxFLf2UTPS1bC7Czkx3pL4fRT9lCvEOKCAD2uiheAmrLGYNC11p92JmgDbdmx2BbKJNV2I1YSPt8vbDacgq5ztIKsNO14TkimnfcRX3y6PBklwi9orsUx3CWODJIiWOM1ozv9YgTp1F1fSqUzLAEzJBUyMQI8yCF-rDmzCwXxVeIrW--7QUK10Qexj_yOfZ1P_PFwLYoQdTmCZofiDxk5btA_UrR81--t0yztyrsMdLeCQYXWBtEjA3_SvXlnpptFpj-iR9BUFwtOMvmbJOnKkHI0-AhghAm5iJipjgPCLM-8M0nmu5hxOPpIXyzAYQHMHY' \
--data-raw ''

Response objects

The API returns a JSON-serialized response containing the beneficiary object:

{
  "account Number": "9382027456", 
  "bankName": "ABSA", 
  "branchCode": "632005",
  "debitDay": null, 
  "debitMonth": null, 
  "trackingDays": null, 
  "accountType": 1, 
  "amount": null, 
  "clientCode": "PSZer001", 
  "clientName": "Zero Zero One", 
  "customerCode": "DEC", 
  "endDate": null, 
  "id": "227095171233202134137140137224843195058098092236", 
  "installments": null, 
  "isActive": false, 
  "name": "Balance", 
  "recurringPeriod": 0, 
  "reference": "TOTHENONO", 
  "scheduleType": 0,
  "serviceCode": "PPREFTWAG", 
  "startDate": null, 
  "tokenHash": "2073F72AEBCED4E823B4DE5DC55057A11BE27FDO"
}
ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
BankNameThe bank name.String
BranchCodeThe beneficiary account branch code.String
DebitDayThe debit day.Integer
DebitMonthThe debit month.Integer
AccountTypeThe account type.Integer
TrackingDaysThe number of tracking days.Integer
AmountThe amount to be paid.Decimal
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
StartDateThe start date.Date
EndDateThe end date.Date
TokenHashA generated token for future use.String

Add or update payment beneficiaries

Request URL

The API supports POST requests to add or update beneficiary records: POST <https://api.peachpay.co.za/api/beneficiaries/payments>

Request parameters

The request body must be submitted to the API via a POST request using the application/json content-type.

Headers

  • Authorization: Bearer {{bearer_token}}
  • Content-Type: application/json

Body

{
  "accountNumber": "123456789", 
  "amount": null, 
  "branchCode": "632005", 
  "clientCode": "PSZer001", 
  "clientName": "Zero Zero One", 
  "customerCode": "236005", 
  "id": null, 
  "isActive": true, 
  "name": "Test12345", 
  "reference":"4300228741100012010", 
  "scheduleType": 0, 
  "serviceCode": "PPREFTSAL"
}

Code snippets

var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/payments/")
client.Timeout = -1;

var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer 3kv7sD1y0jOZ6Vsdv7cQ1_vHdK0nu2zEyr3knH0CSd0uFl0C6eD54sRGMlQuvAgwl3hVZoilEr6mAN5NsDGKwRMxFLf2UTPS1bC7Czkx3pL4fRT9lCvEOKCAD2uiheAmrLGYNC11p92JmgDbdmx2BbKJNV2I1YSPt8vbDacgq5ztIKsNO14TkimnfcRX3y6PBklwi9orsUx3CWODJIiWOM1ozv9YgTp1F1fSqUzLAEzJBUyMQI8yCF-rDmzCwXxVeIrW--7QUK10Qexj_yOfZ1P_PFwLYoQdTmCZofiDxk5btA_UrR81--t0yztyrsMdLeCQYXWBtEjA3_SvXlnpptFpj-iR9BUFwtOMvmbJOnKkHI0-AhghAm5iJipjgPCLM-8M0nmu5hxOPpIXyzAYQHMHY");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n\t\"accountNumber\":\"123456789\",\n\t\"amount\": null,\n\t\"branchCode\" :\"632005\",\n\t\"clientCode\": \"PSZer001\",\n\t\"clientName\": \"Zero ZeroOne\",\n\t\"customerCode\": \"236005\",\n\t\"id\": null,\n\t\"isActive\":true,\n\t\"name\":\"Test12345\",\n\t\"reference\":\"4300228741V00012010\",\n\t\"scheduleType\":0,\n\t\"serviceCode\": \"PPREFTSAL\"\n}", ParameterType.RequestBody);

IRestResponse response = client.Execute(request);
curl --location --request POST 'https://api.peachpay.co.za/api/beneficiaries/payments/' \
--header 'Authorization: Bearer 1DjCRegovjauuoVU5nAsrlCLFTpYTx2C_ScWeIel1FgO9WzWPcL4QkwtwM3Yfds5Nm1oeF4oA4w8RBIjGANWW_yP6vzZuWuqdvCdY1nrUqv1AI2C0DT8HlAwqScjM_20leB67hz6HV6nYugirPPaE_Bh39UbBmxpcOhFi6avDGhL6yJaT3W2jqooyItJ5ueHWcKhVIjAjHBYn9_CdHKCIMBtcp9GMAfMxV308VYkf4VrCwfu46RPjl09334ElLQl5-r3Za28OeNmdGWmZB4C6ocvZqqzIMbbafj_7zkdwfdd8LQMWwUIAt5N3Jwk7kjLI3t8tIsoiqiNsLP_n5RLtq_BrWuyBKW2RTu0Khb5JU2ubSzOahZB8nHnmUPIEV6P8HxEbJCQmIzTi0xpH0chGm8SnU' \
--header 'Content-Type: application/json' \
--data-raw '
{
            "accountNumber": "123456789",
            "amount": null,
            "branchCode": "632005",
            "clientCode": "PSZer001",
            "clientName": "Zero Zero One",
            "customerCode": "236005",
            "id": null,
            "isActive": true,
            "name": "Test12345",
            "reference": "4300228741100012010",
            "scheduleType": 0,
            "serviceCode": "PPREFTSAL"
  }
    '
ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
AmountThe amount to be paid.Decimal
BranchCodeThe beneficiary account branch code.String
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier. Set to null if a new beneficiary is being added.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/");

var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("authorization", "Bearer <your_bearer_token>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "<your_json_string>", ParameterType.RequestBody);

IRestResponse response = client.Execute(request);

Response objects

The API returns a JSON-serialized response containing either the errors for the save action or the
updated beneficiary object.

{
  "accountNumber": "123456789", 
  "bankName": "", 
  "branchCode": "632005", 
  "debitDay": null, 
  "debitMonth": null, 
  "trackingDays": null, 
  "accountType": 0, 
  "amount": null, 
  "clientCode": "PSZer001", 
  "clientName": "Zero Zero One", 
  "customerCode": "236005", 
  "endDate": null, 
  "id": "161064146206078147162116214881156888048238081218", 
  "installments": null, 
  "isActive": true, 
  "name": "Test12345", 
  "recurringPeriod": 0, 
  "reference": "43002287411V00012018", 
  "scheduleType": 0, 
  "serviceCode": "PPREFTSAL", 
  "startDate": null, 
  "tokenHash": "81224E849E6A6E6B8E6C1E3B7249583A3BFD9CE3"
}
ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
BankNameThe bank name.String
BranchCodeThe beneficiary account branch code.String
DebitDayThe debit day.Integer
DebitMonthThe debit month.Integer
AccountTypeThe account type.Integer
TrackingDaysThe number of tracking days.Integer
AmountThe amount to be paid.Decimal
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
StartDateThe start date.Date
EndDateThe end date.Date
TokenHashA generated token for future use.String

Validation errors

Validation errors are returned with the original model state object containing the errors for each individual parameter. The example below shows what happens when an invalid service code is supplied.

{
  "message": "The request is invalid.", 
  "modelState": { 
    "serviceCode": [
      "Invalid service code PPREFTSALT"
    ]
  }
}

New beneficiary or updated beneficiary

The API returns an updated beneficiary object for successful requests. The structure of this object is the same as the normal object returned by the API GET methods.

Search for collection beneficiaries

Overview

The search function enables an API client to search available beneficiaries. If no search criteria
are supplied, all beneficiaries are displayed.

Request URL

The API supports GET requests with a query string to specify the request parameters: GET <https://api.peachpay.co.za/api/beneficiaries/collections>

Request parameters

The following request parameters can be specified on the request query string.

Headers

Authorization: Bearer {{bearer_token}}

ParameterDescriptionConditionDefault value
ClientThe client code you are searching for, as supplied by Peach Payments.Required
ServiceThe service code you are searching for.Required
QueryLiteral text or phrase that can be contained in beneficiary fields. The fields matched include Account Number, Customer Code, Branch Code, Branch Name, Beneficiary Name, and Reference.Optional
PageThe page number to retrieve in a set of results.Optional1
PageSizeThe maximum number of results per page.Optional20

Code snippets

var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/collections/?client=PSZER001&service=PPREFTWAG");
client.Timeout = -1;

var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer 3kv7sD1y0jOZ6Vsdv7cQ1_vHdK0nu2zEyr3knH0CSd0uFl0C6eD54sRGMlQuvAgwl3hVZoilEr6mAN5NsDGKwRMxFLf2UTPS1bC7Czkx3pL4fRT9lCvEOKCAD2uiheAmrLGYNC11p92JmgDbdmx2BbKJNV2I1YSPt8vbDacgq5ztIKsNO14TkimnfcRX3y6PBklwi9orsUx3CWODJIiWOM1ozv9YgTp1F1fSqUzLAEzJBUyMQI8yCF-rDmzCwXxVeIrW--7QUK10Qexj_yOfZ1P_PFwLYoQdTmCZofiDxk5btA_UrR81--t0yztyrsMdLeCQYXWBtEjA3_SvXlnpptF-pjiR9BUFwtOMvmbJOnKkHI0-AhghAm5iJipjgPCLM-8M0nmu5hxOPpIXyzAYQHMHY");

IRestResponse response = client.Execute(request);
curl --location --request GET 'https://api.peachpay.co.za/api/beneficiaries/collections/?client=PSZER001&service=PPREFTWAG' \
--header 'Authorization: Bearer 1DjCRegovjauuoVU5nAsrlCLFTpYTx2C_ScWeIel1FgO9WzWPcL4QkwtwM3Yfds5Nm1oeF4oA4w8RBIjGANWW_yP6vzZuWuqdvCdY1nrUqv1AI2C0DT8HlAwqScjM_20leB67hz6HV6nYugirPPaE_Bh39UbBmxpcOhFi6avDGhL6yJaT3W2jqooyItJ5ueHWcKhVIjAjHBYn9_CdHKCIMBtcp9GMAfMxV308VYkf4VrCwfu46RPjl09334ElLQl5-r3Za28OeNmdGWmZB4C6ocvZqqzIMbbafj_7zkdwfdd8LQMWwUIAt5N3Jwk7kjLI3t8tIsoiqiNsLP_n5RLtq_BrWuyBKW2RTu0Khb5JU2ubSzOahZB8nHnmUPIEV6P8HxEbJCQmIzTi0xpH0chGm8SnU'

Response objects

The API returns a JSON-serialized response containing the matched records for the search request:

{
  "data": [
    {...},
    {...},
    {...}
  ],
  "pageCount": 0,
  "pageNumber": 1, 
  "pageSize": 20, 
  "totalResults": 3
}

This object contains the following parameters:

ParameterDescriptionFormat
DataContains an array of search results.Array
PageCountThe total number of pages for this search request.Integer
PageNumberThe page number for this search request.Integer
PageSizeThe maximum number of results per page.Integer
TotalResultsThe total number of results, without paging, for this search request.Integer

The data parameter contains an array of beneficiary objects.

{
  "data": [
    {
      "accountNumber": "123456789", 
      "amount": 56, 
      "branchCode": "632005", 
      "clientCode": "PSZer001", 
      "clientName": "Zero Zero One",
      "customerCode": "1111", 
      "id": "12221907247084172232052140135883004057143816010", 
      "isActive": true,
      "name": "TEST once off", 
      "reference": "TEST",
      "scheduleType": 2, 
      "serviceCode": "PPREFTSAL", 
      "tokenHash": "591FCB4D11F991821ACDB632384438"
    },
    {...},
    {...}
  ],
  "pageCount": 0,
  "pageNumber": 1, 
  "pageSize": 20, 
  "totalResults": 3
}

The beneficiary object contains the following parameters:

ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
BankNameThe bank name.String
DebitDayThe debit day.Integer
DebitMonthThe debit month.Integer
TrackingDaysThe number of tracking days.Integer
AccountTypeThe account type.Integer
StartDateThe start date.Date
EndDateThe end date.Date
InstallmentsThe number of installments.Integer
RecurringPeriodThe recurring period type.Integer
AmountThe amount to be paid.Decimal
BranchCodeThe beneficiary account branch code.String
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
TokenHashA generated token for future use.String

Manage collection beneficiaries

Overview

The management of beneficiaries consists of two parts, allowing for the retrieval of a beneficiary record by identifier or to update a beneficiary by identifier. This endpoint also enables you to add new beneficiaries.

Retrieve beneficiaries

Request URL

The API supports GET requests with a query string to specify the beneficiary identifier:

  • Using query string parameter: GET <https://api.peachpay.co.za/api/beneficiaries/collections/get?entityKey={{beneficiary_identifier}}>
  • Using route parameter: GET <https://api.peachpay.co.za/api/beneficiaries/collections/{{beneficiary_identifier}}>

Request parameters

The API allows you to retrieve a specific beneficiary record using the beneficiary identifier.

Headers

Authorization: Bearer {{bearer_token}}

ParameterDescriptionCondition
EntityKeyThe beneficiary identifier as returned in the id field for the beneficiary object.Required

Code snippets

var client = new RestClient("https://api.peachpay.co.za/api/beneficiaries/collections/<EntityKey>");

var request = new RestRequest(Method.GET);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("authorization", "Bearer <your_bearer_token>");

IRestResponse response = client.Execute(request);
curl --location --request GET 'https://api.peachpay.co.za/api/beneficiaries/collections/<EntityKey>' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data-raw ''

Response objects

The API returns a JSON-serialized response containing the beneficiary object:

{
  "accountNumber": "123456789", 
  "amount": null, 
  "branchCode": "632005", 
  "clientCode": "PSZer00l",
  "clientName": "Zero Zero One", 
  "customerCode": "213456", 
  "id": "231099182204078052033107147055062191228001150250", 
  "isActive": true, 
  "name": "Test12345",
  "reference": "123465", 
  "scheduleType": 0,
  "serviceCode": "PPREFTSAL",
  "tokenHash": "AB2D59DDC556493956A82A6C267076192377973"
}
ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
AmountThe amount to be paid.Decimal
BranchCodeThe beneficiary account branch code.String
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String
TokenHashA generated token for future use.String

Add or update payment beneficiaries

Request URL

The API supports POST requests to add or update beneficiary records: POST <https://api.peachpay.co.za/api/beneficiaries/collections>

Request parameters

The request body must be submitted to the API via a POST request using the application/json content-type. The request body itself should not contain "application/json": {} inside the body, only the fields required.

Headers

  • Authorization: Bearer {{bearer_token}}
  • Content-Type: application/json

Body

{
  "accountNumber": "123456789",
  "amount": null, 
  "branchCode": "632005",
  "clientCode": "PSZer001", 
  "clientName": "Zero Zero One", 
  "customerCode": "213456", 
  "id": null, 
  "isActive": true, 
  "name": "Test12345", 
  "reference":"123465", 
  "scheduleType": 0, 
  "serviceCode": "PPREFTSAL"
}
ParameterDescriptionFormat
AccountNumberThe beneficiary account number.String
AmountThe amount to be paid.Decimal
BranchCodeThe beneficiary account branch code.String
ClientCodeThe client code provided by Peach Payments.String
ClientNameThe client name.String
CustomerCodeThe customer code.String
IdThe unique beneficiary identifier. Set to blank if a new beneficiary is being added.String
IsActiveThe active or inactive status of this beneficiary.Boolean
NameThe beneficiary name.String
ReferenceThe reference for this beneficiary payment.String
ScheduleTypeThe payment schedule. Valid values include Master = 0, Recurring = 1.Integer
ServiceCodeThe service code.String

Code snippets

var client = new RestClient("http://api.peachpay.co.za/api/beneficiaries/collections");

var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("authorization", "Bearer <your_bearer_token>");
request.AddHeader("content-type", "application/json");

request.AddParameter("application/json", "<your_json_string>", ParameterType.RequestBody);

IRestResponse response = client.Execute(request);
curl --location --request POST 'https://api.peachpay.co.za/api/beneficiaries/collections/' \
--header 'Authorization: Bearer <your_bearer_token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
            "accountNumber": "123456789",
            "amount": null,
            "branchCode": "632005",
            "clientCode": "PSZer001",
            "clientName": "Zero Zero One",
            "customerCode": "213456",
            "id": null,
            "isActive": true,
            "name": "Test12345",
            "reference": "123465",
            "scheduleType": 0,
            "serviceCode": "PPREFTSAL"
  }
    '

Response objects

The API returns a JSON-serialized response containing either the errors for the save action or the updated beneficiary object.

Validation errors

Validation errors are returned with the original model state object containing the errors for each individual parameter. The example below shows what happens when an invalid service code is supplied.

{
  "message": "The request is invalid.", 
  "modelState": { 
    "serviceCode": [
      "Invalid service code PPREFTSALT"
    ]
  }
}

New beneficiary or updated beneficiary

The API returns an updated beneficiary object for successful requests. The structure of this object is the same as the normal object returned by the API GET methods.

{
  "accountNumber": "123456789",
  "bankName": "",
  "branchCode": "632005",
  "debitDay": null,
  "debitMonth": null, 
  "trackingDays": null, 
  "accountType": 0, 
  "amount": null, 
  "clientCode": "PSZer001", 
  "clientName": "Zero Zero One", 
  "customerCode": "236005", 
  "endDate": null, 
  "id": "161064146206078147162116214881156888048238081218", 
  "installments": null, 
  "isActive": true, 
  "name": "Test12345", 
  "recurringPeriod": 0, 
  "reference": "43002287411V00012018", 
  "scheduleType": 0, 
  "serviceCode": "PPREFTSAL", 
  "startDate": null, 
  "tokenHash": "81224E849E6A6E6B8E6C1E3B7249583A3BFD9CE3"
}