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",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "8007014800087",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"is_tax": true,
"tax_number": "9560164031",
"notes": "some notes"
}]
}
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 |
| *.id_type | N | ENUM | Note: Company Registration Number type lookup only applies when using 'company_name'. (COMPANY_REGISTRATION_NUMBER,PASSPORT_NUMBER,SOUTH_AFRICAN_ID,TEMPORARY_RESIDENCE) | SOUTH_AFRICAN_ID |
| *.id_number | C | String(14) | ID number relating to the ID type | 8007014800087 |
| *.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 |
| *.is_tax | N | Boolean | true - Recipient is taxed | true |
| *.tax_number | N | String(64) | Recipient tax number | 9560164031 |
| *.notes | N | String(2048) | Optional notes for the recipient | Some notes. |
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",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "8007014800087",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"is_tax": true,
"tax_number": "9560164031",
"notes": "some notes"
}]
}
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 |
| *.id_type | N | ENUM | Note: Company Registration Number type lookup only applies when using 'company_name'. (COMPANY_REGISTRATION_NUMBER,PASSPORT_NUMBER,SOUTH_AFRICAN_ID,TEMPORARY_RESIDENCE) | SOUTH_AFRICAN_ID |
| *.id_number | C | String(14) | ID number relating to the ID type | 8007014800087 |
| *.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 |
| *.is_tax | N | Boolean | true - Recipient is taxed | true |
| *.tax_number | N | String(64) | Recipient tax number | 9560164031 |
| *.notes | N | String(2048) | Optional notes for the recipient | Some notes. |
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 |
| id_number | String(14) | N | Filter for a specific ID number. | 8007014800087 |
| tax_number | String(64) | N | Filter for a specific tax number. | 9560164031 |
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",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "8007014800087",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"is_tax": true,
"tax_number": "9560164031",
"notes": "some notes"
}, ...]
}
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 |
| *.id_type | ENUM | Note: Company Registration Number type lookup only applies when using 'company_name'. (COMPANY_REGISTRATION_NUMBER,PASSPORT_NUMBER,SOUTH_AFRICAN_ID,TEMPORARY_RESIDENCE) | SOUTH_AFRICAN_ID |
| *.id_number | String(14) | ID number relating to the ID type | 8007014800087 |
| *.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 |
| *.is_tax | Boolean | true - Recipient is taxed | true |
| *.tax_number | String(64) | Recipient tax number | 9560164031 |
| *.notes | String(2048) | Optional notes for the recipient | Some notes. |
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.
Refunds
Refund a settled online card, Apple Pay or Google Pay transaction back to the cardholder. Pass the transaction ID of the original charge with a reason; full or partial amounts are supported.