Money Out
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.
Request
Create batch EFT payouts from the account specified in a payment method to a specified recipient.
Path
POST /payouts/request
Request Body
{
"batch_reference": "PAY23011",
"records": [{
// either pass the recipient_id or the recipient object
"recipient_id": "rcp_6ujw08sqs3d6DyWFj66au",
// create a new recipient
"recipient": {
"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
},
// you can also pass a customer id or object through for refunds
"customer_id": "cus_cldM8OIXkGwBrfd5jjPdD",
// create a new customer
"customer": {
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "8307095800083",
"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
},
// either pass the bank_account_id or the bank_account object
// must be linked to either recipient_id or customer_id when used
"bank_account_id": "ban_XIIlbzHrPWDHjDx3ijcyC",
// create a new bank account
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"payout": {
"recipient_eft_reference": "THEIRREF1234",
"payer_eft_reference": "MYREF1234",
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"payout_date": "2026-05-07",
"transaction_reference": "PAYOUT1234",
"reason_for_payout": "Salary payment",
// indicate PAAF or IIP
"is_immediate": true,
"authorisation": {
"submitting_entity_name": "KWIK",
"subsidiary_entity_name": "HELP NGO",
"prior_authorisation": false
},
"notification": {
"emails": ["support@verge.co.za", "hello@client.co.za"],
"mobile": "+27821234567"
}
}
}, ...]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| batch_reference | N | String(128) | Custom API reference number you may assign to this payout that will also reflect on subsequent transactions. | RFR23011 |
| records | Y | Array of objects | ||
| *.recipient_id | C | String(32) | ID of a specific recipient to pay out. Either a recipient or a customer to pay out must be specified. | rcp_6ujw08sqs3d6DyWFj66au |
| *.recipient.reference | Y | String(35) | Reference to identify a specific recipient. | BAC240919000001 |
| *.recipient.recipient_category. | N | String(32) | Descriptive category string if applicable. | Employee |
| *.recipient.company_name | C | String(64) | Either a company name OR person name and surname must be provided. | Superior Meteor Corp |
| *.recipient.person_name | C | String(32) | Name of the recipient. | John |
| *.recipient.person_surname | C | String(32) | Surname of the recipient. | Doe |
| *.recipient.email | Y | String(128) | Valid email address of the recipient. | johndoe@mail.com |
| *.recipient.contact_number | N | String(16) | Mobile contact number of the recipient. Must include the area code. | +27831234567 |
| *.recipient.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 |
| *.recipient.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 |
| *.recipient.city_or_town | N | String(64) | City/Town where billing address is located in. | Pretoria |
| *.recipient.postal_code | N | Integer | Postal code related to the billing address. | 1285 |
| *.customer_id | C | String(32) | ID of a specific recipient to pay out. Either a recipient or a customer to pay out must be specified. | cus_cldM8OIXkGwBrfd5jjPdD |
| *.customer.reference | Y | String(35) | Reference to identify a specific customer. | CLN240919000001 |
| *.customer.company_name | C | String(64) | Either a company name OR person name and surname must be provided. | Superior Meteor Corp |
| *.customer.person_name | C | String(32) | Name of the customer to receive funds. | John |
| *.customer.person_surname | C | String(32) | Surname of the customer to receive funds. | Doe |
| *.customer.client_type | N | ENUM | For use with Nedbank provided payment methods. Defaults to Resident individual / Domestic company. (DOMESTIC_COMPANY,FINANCIAL_INSTITUTION,FOREIGN_COMPANY,NONRESIDENT_INDIVIDUAL,RESIDENT_INDIVIDUAL). | RESIDENT_INDIVIDUAL |
| *.customer.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 |
| *.customer.id_number | N | String(14) | ID number relating to the ID type | 9004014800083 |
| *.customer.email | Y | String(128) | Valid email address of the customer. | johndoe@mail.com |
| *.customer.contact_number | N | String(16) | Mobile contact number of the customer. Must include the area code. | +27831234567 |
| *.customer.billing_address_line_1 | N | String(128) | First line of address for the customer. Should be the street address if no complex number is applicable. | 145 Superior Complex |
| *.customer.billing_address_line_2 | N | String(128) | Second line of address for the customer. Should be the street address if a complex was used on line 1. | 541 New River Road |
| *.customer.city_or_town | N | String(64) | City/Town where billing address is located in. | Pretoria |
| *.customer.postal_code | N | Integer | Postal code related to the billing address. | 1285 |
| *.bank_account_id | C | String(32) | Either the bank_account_id or bank_account object must be specified. Bank account ID must be linked to the specified recipient ID or the customer ID. | ban_XIIlbzHrPWDHjDx3ijcyC |
| *.bank_account.bank_account_holder_name | Y | String(30) | Bank account holder name to receive the payout. | J DOE |
| *.bank_account.bank_account_number | Y | String(17) | Bank account number to receive the payout. | 10004291601 |
| *.bank_account.bank_account_type | Y | ENUM | (CHEQUE_OR_CURRENT,SAVINGS,TRANSMISSION) | CHEQUE_OR_CURRENT |
| *.bank_account.bank_name | Y | ENUM | (ABSA_BANK_LIMITED,ABSAITHALA,ACCESS_BANK,AFRICAN_BANK,AFRICAN_BANK_BUSINESS_GRINDROD,ALBARAKA_BANK,BANK_WINDHOEK_BEPERK,BANK_ZERO,BIDVEST_BANK,BIDVEST_BANK_LIMITED,BNP_PARIBAS,CAPITEC_BUSINESS,CAPITEC_PERSONAL,DISCOVERY_BANK_LTD,ENL_MUTUAL_BANK,FBC_FIDELITY_BANK_LTD,FINBOND_EPE,FINBOND_MUTUAL_BANK,FIRST_NATIONAL_BANK_LESOTHO,FIRST_NATIONAL_BANK_NAMIBIA,FIRST_NATIONAL_BANK_SWAZILAND,FIRSTRAND_BANK,FNB_FIRST_NATIONAL_BANK,HABIB_OVERSEAS_BANK_LIMITED,HSBC_BANK,INVESTEC_BANK_LIMITED,JP_MORGAN,NEDBANK,NEDBANK_LESOTHO_LIMITED,NEDBANK_NAMIBIA,NEDBANK_SWAZILAND_LIMITED,OLYMPUS_MOBILE,OM_BANK_LIMITED,PEOPLE_BANK_LTD_INC_PEP_BANK,PEOPLES_BANK_LTD_INC_NBS,PERMANENT_BANK,RMB_RAND_MERCHANT_BANK,SA_POST_BANK_POST_OFFICE,SOCIETE_GENERAL_JHB_BRANCH,STANDARD_BANK_NAMIBIA,STANDARD_BANK_SA_LTD,STANDARD_BANK_SWAZILAND,STANDARD_CHARTERED_BANK_SA,STANDARD_LESOTHO_BANK_LTD,SWAZILAND_DEV_AND_SAVINGS_BANK,TYME_BANK_LIMITED,UBANK_LTD,UNIBANK_LIMITED,VBS_MUTUAL_BANK) | ABSA_BANK_LIMITED |
| *.bank_account.bank_branch_code | Y | Integer | Universal bank branch code for the account number. | 632005 |
| *.payout.recipient_eft_reference | Y | String(20) | Reflected on the recipient's bank statement | THEIRREF1234 |
| *.payout.payer_eft_reference | Y | String(20) | Reflected on the payer's bank statement | MYREF1234 |
| *.payout.payment_methods_id | Y | String(32) | ID of the payment method to be used for this payout. | pam_BX4HNZjMMI-tt8_KWyxAq |
| *.payout.amount | Y | Decimal | Amount to be paid out. | 45.00 |
| *.payout.payout_date | Y | Date(YYYY-MM-DD) | The date on which the payout should be made. Can be today or in the future. | 2026-05-07 |
| *.payout.transaction_reference | Y | String(35) | Unique payout reference for the specific transaction. | PAYOUT1234 |
| *.payout.reason_for_payout | N | String(512) | Reason/Note related to the payout | Salary payment |
| *.payout.is_immediate | N | Boolean | When true payout is IIP else PAAF | true |
| *.payout.authorisation.submitting_entity_name | N | String(256) | This field can be used to populate the payout initiating party name irrespective of whether the payout initiate is intended for the party itself or on behalf of a subsidiary entity | KWIK |
| *.payout.authorisation.subsidiary_entity_name | N | String(256) | This field can be used to populate the name of the controlled entity, on whose behalf the Submitting Entity is performing the submission. | HELP NGO |
| *.payment.authorisation.prior_authorisation | N | Boolean | Used for Interoperability: This field can be used to indicate if the payment initiator would like to authorize a payment (via an online platform) prior to processing. Payment method can override this setting when prior authorisation override is used. | false |
| *.payout.notification.emails | N | ARRAY | Array of email addresses to send proof of payout to. | "support@verge.co.za", "hello@client.co.za" |
| *.payout.notification.mobile | C | String(12) | May only be provided if at least 1 email has been specified. South african mobile number to send proof of payout to. | +27821234567 |
Response Body
The response follows the same format as the list response
{
"status": true,
"records": [{
"batch_reference": "PAY23011",
"payout_id": "pyo_6ujw0A5qs3g6DeWf4665e",
"payout": {
"payout_status": "ACCEPTED",
"recipient_eft_reference": "THEIRREF1234",
"payer_eft_reference": "MYREF1234",
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"payout_date": "2026-05-07",
"transaction_reference": "PAYOUT1234",
...
},
...
}, ...]
}
Examples
Recipient Payout
{
"records": [{
"recipient": {
"reference": "BAC240919000001",
"recipient_category": "Employee",
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com"
},
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"payout": {
"recipient_eft_reference": "THEIRREF1234",
"payer_eft_reference": "MYREF1234",
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"payout_date": "2026-05-07",
"transaction_reference": "PAYOUT1234",
"reason_for_payout": "Salary payment",
}
}, ...]
}
Customer Payout
{
"records": [{
"customer_id": "cus_cldM8OIXkGwBrfd5jjPdD",
"bank_account_id": "ban_XIIlbzHrPWDHjDx3ijcyC",
"payout": {
"recipient_eft_reference": "THEIRREF1234",
"payer_eft_reference": "MYREF1234",
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"payout_date": "2026-05-07",
"transaction_reference": "PAYOUT1234",
"reason_for_payout": "Salary payment",
}
}, ...]
}
List
List the payouts on the platform.
Path
GET /payouts/list?{params}
Query Parameters
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| batch_reference | N | String(128) | Custom API reference number to filter for. | RFR23011 |
| transaction_reference | N | String(35) | Unique payout reference to filter for. | PAYOUT1234 |
| recipient_eft_reference | N | String(20) | Reflected on the recipient's bank statement. | THEIRREF1234 |
| payer_eft_reference | N | String(20) | Reflected on the payer's bank statement. | MYREF1234 |
| recipient_id | N | String(32) | ID of a recipient to search for. | rcp_6ujw08sqs3d6DyWFj66au |
| customer_id | N | String(32) | ID of a customer to search for. | cus_cldM8OIXkGwBrfd5jjPdD |
| bank_account_id | N | String(32) | ID of a bank account to search for. | ban_XIIlbzHrPWDHjDx3ijcyC |
| recipient_email | N | String(128) | Recipient email to search for. | johndoe@mail.com |
| customer_email | N | String(128) | Customer email to search for. | johndoe@mail.com |
| date_created_start | N | Date(YYYY-MM-DD) | Filter for records created on or after this date. | 2026-05-21 |
| date_created_end | N | Date(YYYY-MM-DD) | Filter for records created up to this date. | 2026-05-22 |
| date_updated_start | N | Date(YYYY-MM-DD) | Filter for records updated on or after this date. | 2026-05-21 |
| date_updated_end | N | Date(YYYY-MM-DD) | Filter for records updated up to this date. | 2026-05-22 |
Response Body
{
"status": true,
"records": [{
"batch_reference": "PAY23011",
"payout_id": "pyo_6ujw0A5qs3g6DeWf4665e",
"payout": {
"deleted_at": null,
"updated_at": "2024-05-02 16:12:01",
"created_at": "2024-05-02 15:00:45",
"payout_status": "ACCEPTED",
"recipient_eft_reference": "THEIRREF1234",
"payer_eft_reference": "MYREF1234",
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"payout_date": "2026-05-07",
"transaction_reference": "PAYOUT1234",
"reason_for_payout": "Salary payment",
"is_immediate": true,
"authorisation": {
"submitting_entity_name": "KWIK",
"subsidiary_entity_name": "HELP NGO",
"prior_authorisation": false
},
"notification": {
"emails": ["support@verge.co.za", "hello@client.co.za"],
"mobile": "+27821234567"
}
},
"recipient_id": "rcp_6ujw08sqs3d6DyWFj66au",
"recipient": {
"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
},
"customer_id": "cus_cldM8OIXkGwBrfd5jjPdD",
"customer": {
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "8307095800083",
"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
},
"bank_account_id": "ban_XIIlbzHrPWDHjDx3ijcyC",
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
}, ...]
}
Response Parameters
Field | Type | Description | Example |
|---|---|---|---|
| status | Boolean | true - success, false - error | true |
| records | Array of objects | ||
| *.batch_reference | String(128) | Custom API reference number assigned to the payout | RFR23011 |
| *.payout_id | String(32) | ID of the related payout | pyo_6ujw0A5qs3g6DeWf4665e |
| *.payout.created_at | Date(YYYY-MM-DD HH:mm:ss) | When the payout record was created | 2024-05-02 15:00:45 |
| *.payout.updated_at | Date(YYYY-MM-DD HH:mm:ss) | When last the payout record was updated | 2024-05-02 16:02:01 |
| *.payout.deleted_at | Date(YYYY-MM-DD HH:mm:ss) | When the payout record was deleted | 2024-05-02 16:02:01 |
| *.payout.payout_status | ENUM | (NONE,SAVED, QUEUED, ACCEPTED, REJECTED, NO_RESPONSE, INTERNAL_ERROR, SYSTEM_ERROR, DUPLICATE) | ACCEPTED |
| *.payout.recipient_eft_reference | String(20) | Reflected on the recipient's bank statement | THEIRREF1234 |
| *.payout.payer_eft_reference | String(20) | Reflected on the payer's bank statement | MYREF1234 |
| *.payout.payment_methods_id | String(32) | ID of the payment method to be used for this payout. | pam_BX4HNZjMMI-tt8_KWyxAq |
| *.payout.amount | Decimal | Amount to be paid out. | 45.00 |
| *.payout.payout_date | Date(YYYY-MM-DD) | The payout date. | 2026-05-07 |
| *.payout.transaction_reference | String(35) | Unique payout reference for the specific transaction. | PAYOUT1234 |
| *.payout.reason_for_payout | String(512) | Reason/Note related to the payout | Salary payment |
| *.payout.is_immediate | Boolean | When true payout is IIP else PAAF | true |
| *.payout.authorisation.submitting_entity_name | String(256) | This field can be used to populate the payout initiating party name irrespective of whether the payout initiate is intended for the party itself or on behalf of a subsidiary entity | KWIK |
| *.payout.authorisation.subsidiary_entity_name | String(256) | This field can be used to populate the name of the controlled entity, on whose behalf the Submitting Entity is performing the submission. | HELP NGO |
| *.payment.authorisation.prior_authorisation | Boolean | Indicates if the payment initiator would like to authorize a payment (via an online platform) prior to processing | false |
| *.payout.notification.emails | ARRAY | Array of proof of payout emails. | "support@verge.co.za", "hello@client.co.za" |
| *.payout.notification.mobile | String(12) | South african mobile number to send proof of payout to. | +27821234567 |
| *.recipient_id | String(32) | Payout recipient ID. | rcp_6ujw08sqs3d6DyWFj66au |
| *.recipient.reference | String(35) | Reference to identify a specific recipient. | BAC240919000001 |
| *.recipient.recipient_category. | String(32) | Descriptive category string if applicable. | Employee |
| *.recipient.company_name | String(64) | Recipient company name. | Superior Meteor Corp |
| *.recipient.person_name | String(32) | Name of the recipient. | John |
| *.recipient.person_surname | String(32) | Surname of the recipient. | Doe |
| *.recipient.email | String(128) | Email address of the recipient. | johndoe@mail.com |
| *.recipient.contact_number | String(16) | Mobile contact number of the recipient. | +27831234567 |
| *.recipient.billing_address_line_1 | String(128) | First line of address for the recipient. | 145 Superior Complex |
| *.recipient.billing_address_line_2 | String(128) | Second line of address for the recipient. | 541 New River Road |
| *.recipient.city_or_town | String(64) | City/Town where billing address is located in. | Pretoria |
| *.recipient.postal_code | Integer | Postal code related to the billing address. | 1285 |
| *.customer_id | String(32) | Payout customer ID. | cus_cldM8OIXkGwBrfd5jjPdD |
| *.customer.reference | String(35) | Reference to identify a specific customer. | CLN240919000001 |
| *.customer.company_name | String(64) | Customer company name. | Superior Meteor Corp |
| *.customer.person_name | String(32) | Name of the customer. | John |
| *.customer.person_surname | String(32) | Surname of the customer. | Doe |
| *.customer.client_type | ENUM | (DOMESTIC_COMPANY,FINANCIAL_INSTITUTION,FOREIGN_COMPANY,NONRESIDENT_INDIVIDUAL,RESIDENT_INDIVIDUAL). | RESIDENT_INDIVIDUAL |
| *.customer.id_type | ENUM | (COMPANY_REGISTRATION_NUMBER,PASSPORT_NUMBER,SOUTH_AFRICAN_ID,TEMPORARY_RESIDENCE). | SOUTH_AFRICAN_ID |
| *.customer.id_number | String(14) | ID number relating to the ID type | 9004014800083 |
| *.customer.email | String(128) | Valid email address of the customer. | johndoe@mail.com |
| *.customer.contact_number | String(16) | Mobile contact number of the customer. | +27831234567 |
| *.customer.billing_address_line_1 | String(128) | First line of address for the customer | 145 Superior Complex |
| *.customer.billing_address_line_2 | String(128) | Second line of address for the customer. | 541 New River Road |
| *.customer.city_or_town | String(64) | City/Town where billing address is located in. | Pretoria |
| *.customer.postal_code | Integer | Postal code related to the billing address. | 1285 |
| *.bank_account_id | String(32) | Bank account ID related to the payout | ban_XIIlbzHrPWDHjDx3ijcyC |
| *.bank_account.bank_account_holder_name | String(30) | Bank account holder name. | J DOE |
| *.bank_account.bank_account_number | String(17) | Bank account number. | 10004291601 |
| *.bank_account.bank_account_type | ENUM | (CHEQUE_OR_CURRENT,SAVINGS,TRANSMISSION) | CHEQUE_OR_CURRENT |
| *.bank_account.bank_name | ENUM | (ABSA_BANK_LIMITED,ABSAITHALA,ACCESS_BANK,AFRICAN_BANK,AFRICAN_BANK_BUSINESS_GRINDROD,ALBARAKA_BANK,BANK_WINDHOEK_BEPERK,BANK_ZERO,BIDVEST_BANK,BIDVEST_BANK_LIMITED,BNP_PARIBAS,CAPITEC_BUSINESS,CAPITEC_PERSONAL,DISCOVERY_BANK_LTD,ENL_MUTUAL_BANK,FBC_FIDELITY_BANK_LTD,FINBOND_EPE,FINBOND_MUTUAL_BANK,FIRST_NATIONAL_BANK_LESOTHO,FIRST_NATIONAL_BANK_NAMIBIA,FIRST_NATIONAL_BANK_SWAZILAND,FIRSTRAND_BANK,FNB_FIRST_NATIONAL_BANK,HABIB_OVERSEAS_BANK_LIMITED,HSBC_BANK,INVESTEC_BANK_LIMITED,JP_MORGAN,NEDBANK,NEDBANK_LESOTHO_LIMITED,NEDBANK_NAMIBIA,NEDBANK_SWAZILAND_LIMITED,OLYMPUS_MOBILE,OM_BANK_LIMITED,PEOPLE_BANK_LTD_INC_PEP_BANK,PEOPLES_BANK_LTD_INC_NBS,PERMANENT_BANK,RMB_RAND_MERCHANT_BANK,SA_POST_BANK_POST_OFFICE,SOCIETE_GENERAL_JHB_BRANCH,STANDARD_BANK_NAMIBIA,STANDARD_BANK_SA_LTD,STANDARD_BANK_SWAZILAND,STANDARD_CHARTERED_BANK_SA,STANDARD_LESOTHO_BANK_LTD,SWAZILAND_DEV_AND_SAVINGS_BANK,TYME_BANK_LIMITED,UBANK_LTD,UNIBANK_LIMITED,VBS_MUTUAL_BANK) | ABSA_BANK_LIMITED |
| *.bank_account.bank_branch_code | Integer | Universal bank branch code for the account number. | 632005 |