Money Out
Recipients
Manage recipient records for use with payouts.
Used to create, edit and archive recipients.
Create
API call to create new recipient(s) as single or batch records.
Path
POST /recipients/create
Request Body
{
"records": [{
"reference": "BAC240919000001",
"recipient_category": "Employee",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285
}]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| *.reference | Y | String(35) | Reference to identify a specific recipient. | BAC240919000001 |
| *.recipient_category. | N | String(32) | Descriptive category string if applicable. | Employee |
| *.company_name | C | String(64) | Either a company name OR person name and surname must be provided. | Superior Meteor Corp |
| *.person_name | C | String(32) | Name of the recipient. | John |
| *.person_surname | C | String(32) | Surname of the recipient. | Doe |
| Y | String(128) | Valid email address of the recipient. | johndoe@mail.com | |
| *.contact_number | N | String(16) | Mobile contact number of the recipient. Must include the area code. | +27831234567 |
| *.billing_address_line_1 | N | String(128) | First line of address for the recipient. Should be the street address if no complex number is applicable. | 145 Superior Complex |
| *.billing_address_line_2 | N | String(128) | Second line of address for the recipient. Should be the street address if a complex was used on line 1. | 541 New River Road |
| *.city_or_town | N | String(64) | City/Town where billing address is located in. | Pretoria |
| *.postal_code | N | Integer | Postal code related to the billing address. | 1285 |
Response Body
The response follows the same format as the list response
{
"status": true,
"records": [{
"id": "rcp_6ujw08sqs3d6DyWFj66au",
"recipient_status": "ACTIVE",
...
}, ...]
}
Update
API call to update existing recipient(s) as single or batch records. Records can not be deleted, only archived.
Path
POST /recipients/update
Request Body
Only include fields you wish to change (besides id used to find the record). Setting a column to null e.g. city_or_town = null will clear that fields' value if allowed.
{
"records": [{
"id": "rcp_6ujw08sqs3d6DyWFj66au",
"recipient_status": "DISABLED",
"reference": "BAC240919000001",
"recipient_category": "Employee",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285
}]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| *.id | Y | String(35) | ID of the recipient to be updated | rcp_6ujw08sqs3d6DyWFj66au |
| *.recipient_status | N | ENUM | (ACTIVE, ARCHIVED, DISABLED) | ACTIVE |
| *.reference | N | String(35) | Reference to identify a specific recipient. | BAC240919000001 |
| *.recipient_category. | N | String(32) | Descriptive category string if applicable. | Employee |
| *.company_name | N | String(64) | Either a company name OR person name and surname must be provided. | Superior Meteor Corp |
| *.person_name | N | String(32) | Name of the recipient. | John |
| *.person_surname | N | String(32) | Surname of the recipient. | Doe |
| N | String(128) | Valid email address of the recipient. | johndoe@mail.com | |
| *.contact_number | N | String(16) | Mobile contact number of the recipient. Must include the area code. | +27831234567 |
| *.billing_address_line_1 | N | String(128) | First line of address for the recipient. Should be the street address if no complex number is applicable. | 145 Superior Complex |
| *.billing_address_line_2 | N | String(128) | Second line of address for the recipient. Should be the street address if a complex was used on line 1. | 541 New River Road |
| *.city_or_town | N | String(64) | City/Town where billing address is located in. | Pretoria |
| *.postal_code | N | Integer | Postal code related to the billing address. | 1285 |
Response Body
The response follows the same format as the list response
{
"status": true,
"records": [{
"id": "cus_9F3jl6zuRAJxuBmiN3H4D",
"customer_status": "ACTIVE",
...
}, ...]
}
List
List recipients loaded on the platform.
Path
GET /recipients/list?{params}
Query Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| recipient_status | ENUM | N | Filter for a specific customer status. (ACTIVE,ARCHIVED,DISABLED). | ACTIVE |
| date_start | Date(YYYY-MM-DD) | N | Filter for records that have a created date on or after after this date specified. | 2024-09-13 |
| date_end | Date(YYYY-MM-DD) | N | Filter for records up to this created date | 2025-04-24 |
| recipient_id | String(32) | N | Filter for a specific recipient id. | rcp_6ujw08sqs3d6DyWFj66au |
| reference | String(35) | N | Filter for a specific recipient reference. | BAC240919000001 |
| company_name | String(64) | N | Filter for a specific company names. | Fast Corp LTD |
| person_name | String(32) | N | Filter for a specific name. | John |
| person_surname | String(32) | N | Filter for a specific surname. | Doe |
| String(128) | N | Filter for a specific email. | johndoe@mail.com | |
| contact_number | String(16) | N | Filter for a specific contact number. | 27831234567 |
Response Body
{
"status": true,
"records": [{
"id": "rcp_6ujw08sqs3d6DyWFj66au",
"recipient_status": "DISABLED",
"deleted_at": null,
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"reference": "BAC240919000001",
"recipient_category": "Employee",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285
}, ...]
}
Response Parameters
Field | Type | Description | Example |
|---|---|---|---|
| status | Boolean | true - success, false - error | true |
| records | Array of objects | ||
| *.id | String(35) | ID of the recipient | rcp_6ujw08sqs3d6DyWFj66au |
| *.recipient_status | ENUM | (ACTIVE, ARCHIVED, DISABLED) | ACTIVE |
| *.deleted_at | Date(YYYY-MM-DD HH:mm:ss) | Date when record was deleted | 2025-05-27 09:11:23 |
| *.updated_at | Date(YYYY-MM-DD HH:mm:ss) | Date when record was last updated | 2025-05-21 09:11:23 |
| *.created_at | Date(YYYY-MM-DD HH:mm:ss) | Date when record was created | 2025-05-01 09:11:23 |
| *.reference | String(35) | Reference to identify a specific recipient. | BAC240919000001 |
| *.recipient_category. | String(32) | Descriptive category string if applicable. | Employee |
| *.company_name | String(64) | Recipient company name. | Superior Meteor Corp |
| *.person_name | String(32) | Name of the recipient. | John |
| *.person_surname | String(32) | Surname of the recipient. | Doe |
| String(128) | Valid email address of the recipient. | johndoe@mail.com | |
| *.contact_number | String(16) | Mobile contact number of the recipient. | +27831234567 |
| *.billing_address_line_1 | String(128) | First line of address for the recipient. | 145 Superior Complex |
| *.billing_address_line_2 | String(128) | Second line of address for the recipient. | 541 New River Road |
| *.city_or_town | String(64) | City/Town where billing address is located in. | Pretoria |
| *.postal_code | Integer | Postal code related to the billing address. | 1285 |
Payouts
Send money to customer bank accounts and manage outbound transfers. Create single or batch payouts with real-time status tracking, beneficiary management, and comprehensive transaction reporting.
CDV
Validate South African account numbers using Check Digit Verification algorithms. Ensure data integrity and reduce collection failures by verifying customer identification and bank account details before processing.