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 get a token, submit a POST (x-www-form-urlencoded) request to <https://api.peachpay.co.za/token> with the following key-value pairs:

Parameter	Description	Condition
`Username`	Your peachpay.co.za portal username.	Required
`Password`	Your peachpay.co.za portal password.	Required
`Grant_type`	`password`.	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, the JSON response contains an access token. An error response occurs if the request fails.

{
  "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

Submit all requests with an Authorization header to ensure processing. 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 you don't provide any search criteria, the API displays all beneficiaries.

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

You can specify the following parameters on the request query string.

Headers

Authorization: Bearer {{bearer_token}}

Parameter	Description	Condition	Default value
`Client`	The client code you are searching for, as supplied by Peach Payments.	Required
`Service`	The service code you are searching for.	Required
`Query`	Literal text or phrase that beneficiary fields could contain. The fields matched include Account Number, Customer Code, Branch Code, Branch Name, Beneficiary Name, and Reference.	Optional
`Page`	The page number to retrieve in a set of results.	Optional	`1`
`PageSize`	The maximum number of results per page.	Optional	`20`

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-serialised 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:

Parameter	Description	Format
`PageData`	Contains the paging information as an object.	Object
`Results`	The data parameter containing an array of search results.	Array

The results object contains the following parameters:

Parameter	Description	Format
`ApprovedBeneficiaryCode`	The code for authorised beneficiaries, for example, SARS, MultiChoice, and so on.	String
`AccountType`	The account type.	Integer
`Amount`	The payment amount.	Decimal
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client's name.	String
`CustomerCode`	The customer code.	String
`EndDate`	The end date.	Date
`Id`	The unique beneficiary identifier.	String
`Installments`	The number of installments.	Integer
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary's name.	String
`RecurringPeriod`	The recurring period type.	Integer
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The service code.	String
`StartDate`	The start date.	Date
`TokenHash`	A 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}}

Parameter	Description	Condition
`EntityKey`	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-serialised 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"
}

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`BankName`	The bank name.	String
`BranchCode`	The beneficiary account branch code.	String
`DebitDay`	The debit day.	Integer
`DebitMonth`	The debit month.	Integer
`AccountType`	The account type.	Integer
`TrackingDays`	The number of tracking days.	Integer
`Amount`	The payment amount.	Decimal
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The service code.	String
`StartDate`	The start date.	Date
`EndDate`	The end date.	Date
`TokenHash`	A 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

Submit the request body 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"
  }
    '

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`Amount`	The payment amount.	Decimal
`BranchCode`	The beneficiary account branch code.	String
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier. Set to null if you're adding a new beneficiary.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The 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-serialised 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"
}

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`BankName`	The bank name.	String
`BranchCode`	The beneficiary account branch code.	String
`DebitDay`	The debit day.	Integer
`DebitMonth`	The debit month.	Integer
`AccountType`	The account type.	Integer
`TrackingDays`	The number of tracking days.	Integer
`Amount`	The payment amount.	Decimal
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The service code.	String
`StartDate`	The start date.	Date
`EndDate`	The end date.	Date
`TokenHash`	A generated token for future use.	String

Validation errors

Validation errors occur with the original model state object containing the errors for each individual parameter. The example below shows what happens when you provide an invalid service code.

{
  "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 standard object returned by the API GET methods.

Search for collection beneficiaries

Overview

The search function enables an API client to search available beneficiaries. If you don't provide any search criteria, the API displays all beneficiaries.

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

Specify the following parameters on the request query string.

Headers

Authorization: Bearer {{bearer_token}}

Parameter	Description	Condition	Default value
`Client`	The client code you are searching for, as supplied by Peach Payments.	Required
`Service`	The service code you are searching for.	Required
`Query`	Literal text or phrase that beneficiary fields could contain. The fields matched include Account Number, Customer Code, Branch Code, Branch Name, Beneficiary Name, and Reference.	Optional
`Page`	The page number to retrieve in a set of results.	Optional	`1`
`PageSize`	The maximum number of results per page.	Optional	`20`

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-serialised response containing the matched records for the search request:

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

This object contains the following parameters:

Parameter	Description	Format
`Data`	Contains an array of search results.	Array
`PageCount`	The total number of pages for this search request.	Integer
`PageNumber`	The page number for this search request.	Integer
`PageSize`	The maximum number of results per page.	Integer
`TotalResults`	The 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:

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`BankName`	The bank name.	String
`DebitDay`	The debit day.	Integer
`DebitMonth`	The debit month.	Integer
`TrackingDays`	The number of tracking days.	Integer
`AccountType`	The account type.	Integer
`StartDate`	The start date.	Date
`EndDate`	The end date.	Date
`Installments`	The number of installments.	Integer
`RecurringPeriod`	The recurring period type.	Integer
`Amount`	The payment amount.	Decimal
`BranchCode`	The beneficiary account branch code.	String
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`g`=`1`.	Integer
`ServiceCode`	The service code.	String
`TokenHash`	A 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}}

Parameter	Description	Condition
`EntityKey`	The 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-serialised 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"
}

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`Amount`	The payment amount.	Decimal
`BranchCode`	The beneficiary account branch code.	String
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The service code.	String
`TokenHash`	A 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

Submit the request body to the API via a POST request using the application/json content-type. The request body itself should contain the required fields and not "application/json": {}.

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"
}

Parameter	Description	Format
`AccountNumber`	The beneficiary account number.	String
`Amount`	The payment amount.	Decimal
`BranchCode`	The beneficiary account branch code.	String
`ClientCode`	The client code provided by Peach Payments.	String
`ClientName`	The client name.	String
`CustomerCode`	The customer code.	String
`Id`	The unique beneficiary identifier. Set to blank if you're adding a new beneficiary.	String
`IsActive`	The active or inactive status of this beneficiary.	Boolean
`Name`	The beneficiary name.	String
`Reference`	The reference for this beneficiary payment.	String
`ScheduleType`	The payment schedule. Valid values include `Master` = `0`, `Recurring` = `1`.	Integer
`ServiceCode`	The 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-serialised response containing either the errors for the save action or the updated beneficiary object.

Validation errors

Validation errors occur with the original model state object containing the errors for each individual parameter. The example below shows what happens when you provide an invalid service code.

{
  "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 standard 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"
}

Postman collection

See the Peach Payments Postman collection for sample calls.