Specification
Payouts
Payout API calls
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",
"payouts": [{
"recipient": {
"reference": "CLN240919000001",
"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,
"bank": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "10004291601",
"bank_account_type_lookups_id": "loo_abc123...",
"bank_name_lookups_id": "loo_abc123...",
"bank_branch_code": 632005
},
"eft_reference": "THEIR REF1234"
},
"payment": {
"eft_reference": "MY REF1234",
"payment_methods_id": "pam_abc123...",
"amount": "45.00",
"transaction_reference": "PAYOUT1234",
"is_immediate": true
}
}, ...]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| batch_reference | N | String(128) | Custom API reference number you may assign to this collection that will also reflect on subsequent transactions. | RFR23011 |
| payouts | Y | Array of objects | ||
| *.recipient.reference | Y | String(35) | Reference to identify a specific customer | CLN240919000001 |
| *.recipient.company_name | N | String(64) | Either a company name OR person name and surname must be provided. Company name is used when collection is made from a specific company | Superior Meteor Corp |
| *.recipient.person_name | N | String(32) | Name of the person to be collected from | John |
| *.recipient.person_surname | N | String(32) | Surname of the person to be collected from | Doe |
| *.recipient.email | N | String(128) | Valid email address of the person to be collected from | johndoe@mail.com |
| *.recipient.contact_number | N | String(16) | Mobile contact number of the person to be collected from. Must include the area code. | +27831234567 |
| *.recipient.billing_address_line_1 | N | String(128) | First line of address for the person to be collected from. 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 person to be collected from. 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 address lines 1 and 2 are located in. | Pretoria |
| *.recipient.postal_code | N | Integer | Postal code related to address lines 1 and 2. | 1285 |
| *.recipient.bank.bank_account_holder_name | Y | String(30) | Bank account holder name for the bank account to be collected from | J DOE |
| *.recipient.bank.bank_account_number | Y | String(17) | Bank account number to be collected from | 10004291601 |
| *.recipient.bank.bank_account_type_lookups_id | Y | String(32) | Lookups ID relating to a bank account e.g. Cheque. Lookups type must be 'Bank Account' | loo_abc123... |
| *.recipient.bank.bank_name_lookups_id | Y | String(32) | Lookups ID relating to the bank name of the account number e.g. ABSA. Lookups type must be 'Bank Name' | loo_abc123... |
| *.recipient.bank.bank_branch_code | Y | Integer | Bank branch code for the account number | 632005 |
| *.recipient.eft_reference | N | String(20) | Reference to be used for the EFT payment that will appear in the recipient bank account, if left blank a reference will be generated | MYREF1234 |
| *.payment.eft_reference | N | String(20) | Reference to be used for the EFT payment that will appear in your bank account, if left blank a reference will be generated | MYREF1234 |
| *.payment.payment_methods_id | Y | String(32) | ID of the payment method to be used to specify the account paying from payment methods | pam_abc123... |
| *.payment.amount | Y | Decimal | The amount to be paid by the customer | 45.00 |
| *.payment.transaction_reference | Y | String(128) | Reference used internally to identify a specific transaction | PAYOUT1234 |
| *.payment.is_immediate | Y | Boolean | Boolean to make an immediate or normal EFT payment | TRUE/FALSE |
Response Body
Display's the floating account details for the customer to make the payment to.
{
"status": true,
"batch_reference": "PAY23011",
"payouts": [{
"transaction_reference": "TRANS1234",
"transaction_status_lookups_id": "loo_abc123...",
"transaction_date": "2024-02-03 08:14:35"
}, ...]
}
Response Parameters
Field | Description | Example |
|---|---|---|
| status | true - successfully requested, false - failed | true |
| batch_reference | Custom API reference number you may assign to this collection that will also reflect on subsequent transactions. | RFR23011 |
| payouts | Payout details | |
| *.transaction_reference | Reference used internally to identify a specific transaction | TRANS1234 |
| *.transaction_status_lookups_id | Lookups ID relating to the status of this transaction e.g. paid, unpaid etc | loo_abc123... |
| *.transaction_date | When the new transaction was billed | 2024-02-03 08:14:35 |