Cashout Requests

Currently, users can only initiate cashout requests through the Osigu Payments web interface. Although the platform supports several endpoints for these tasks, access to these endpoints is restricted to internal processes, and clients have read-only access to cashout-related information. This section overviews the data structure and critical information maintained in each cashout request.

When users initiate a cash advance request from the web, they can select one or multiple invoices, even if they are issued to different payers. This action creates a cashout_request record, which includes a cashout_request_details sub-record containing the specific invoices in the request.

Cashout Request Data Structure

Each cashout request maintains the following fields:

• id: The cashout request's unique identifier (UUID).
• requested_amount: The eligible amount for a cash advance based on the applicable percentage of each included invoice.
• requested_invoice_count: The total number of invoices included in the cashout request.
• paid_invoice_count: The number of invoices that were ultimately paid. Usually, this matches requested_invoice_count, but in some cases, certain invoices may be excluded.
• paid_amount: The actual amount paid may differ if any invoices were excluded from the original request. It will be null if the payment is pending.
• request_date: The date the cashout request was created.
• payment_date: The date the cash advance was executed.
• payment_reference: The payment reference or ID returned by the payment processor.
• status: The current status of the request, which can be one of the following: REQUESTED,APPROVED, PAID,CANCELLED, REJECTED, PENDING_PAYMENT, UNDER_REVIEW, PAYMENT_PROCESSOR_ERROR.
• requested_by: The user who submitted the cash advance request.

Status Flow for Cashout Requests

The status flow for cashout requests follows a specific sequence, with transitions based on user actions and system processes. Here is the typical status flow:

Each status transition in the cashout request also impacts the status of each included invoice, ensuring alignment across records.

Webhooks for Cashout Requests

A webhook is triggered each time a new cashout request is created, allowing providers to receive real-time updates and synchronize their internal systems. Additionally, a webhook is triggered for every status change in a cashout request, providing updates throughout the request's lifecycle. For more information on setting up and handling these webhooks, refer to the Webhooks section.