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 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.
Updated about 22 hours ago