Batch Payout
Batch Payouts API Documentation
Endpoint: POST
``{{baseUrl}}/payout/batch
This endpoint processes batch payout requests. It validates the input data, checks if beneficiaries and their payment methods exist, creates withdrawal records, and processes payouts using a payment service.
Request
URL:
{{baseUrl}}/payout/batch
Method:
POST
Content-Type:
application/json
Request Body:
{ "payouts": [ { "beneficiary_id": 1, "amount": 100.00, "beneficiary_details_id": 1 }, { "beneficiary_id": 2, "amount": 150.00, "beneficiary_details_id": 2 } ] }
Response
Success Response:
Status: 200 OK
Body:
{ "status": "success", "status_code": 200, "message": "Batch withdrawal requests processed successfully", "data": [ { "beneficiary_id": 1, "amount": 100.00, "gateway": "example_gateway", "currency": "USD", "transaction_details": { /* payout details */ } }, { "beneficiary_id": 2, "amount": 150.00, "gateway": "example_gateway", "currency": "USD", "transaction_details": { /* payout details */ } } ] }
Error Response:
Status: 400 Bad Request
Body:
{ "status": "failed", "status_code": 400, "message": "Request failed", "data": { "errors": [ { "error": "Beneficiary not found" }, { "error": "Beneficiary not found" } ] } }
Error Handling
The following are common error scenarios and their responses:
Validation Errors:
Status: 400 Bad Request
Body: Validation errors will be detailed in the response.
Beneficiary Not Found:
Status: 400 Bad Request
Body:
{ "status": "failed", "status_code": 400, "message": "Request failed", "data": { "errors": [ { "error": "Beneficiary not found" } ] } }
Invalid Payout Method:
Status: 400 Bad Request
Body:
{ "status": "failed", "status_code": 400, "message": "Request failed", "data": { "errors": [ { "error": "The selected beneficiary has no valid payout method" } ] } }
Payment Processing Error:
Status: 400 Bad Request
Body:
{ "status": "failed", "status_code": 400, "message": "Request failed", "data": { "errors": [ { "error": "Payment processing error" } ] } }
Internal Server Error:
Status: 500 Internal Server Error
Body:
{ "status": "error", "status_code": 500, "message": "Internal server error", "data": { "error": "Detailed error message" } }
Explanation:
Input Validation:
The request is validated to ensure it contains an array of payouts, each with a
beneficiary_id
,amount
, andbeneficiary_details_id
.
Error Handling:
If validation fails, an error response is returned immediately.
Errors are collected for each payout request and processed at the end.
Database Transaction:
The code runs within a database transaction to ensure atomicity.
For each payout, it checks the existence of the beneficiary and the validity of the payment method.
Withdrawal Creation:
If all checks pass, a withdrawal record is created.
Payment is processed using the
PayoutService
.Any errors encountered are recorded and returned after processing all payouts.
Response:
A success response includes details of each successful payout.
Errors are returned with appropriate status codes and messages.
Last updated