Payouts REST API — Documentation

Date: 2026-05-07 Status: Implemented Module: AffiliateSupport Scope: REST API endpoints for payout management, payout requests, and payout settings

1. Objective

Expose the full functionality of the Payouts management system as external REST API endpoints. These endpoints let third-party systems:

• List payouts with filtering, searching, and pagination
• Retrieve a single payout with full details
• View aggregated payout statistics
• Transition payout status (pending → processing → completed/failed)
• Bulk process multiple payouts at once
• Manage affiliate payout requests (approve/reject)
• Export payouts as CSV
• Download PDF payout statements
• Read and update payout settings (frequency, minimum, early requests)

2. Authentication & Scopes

All endpoints require a Bearer token issued via the Access Token system.

2.1 Scopes

2.2 Authentication Header

Authorization: Bearer <access_token>

2.3 Error Responses

HTTP 401 — Unauthorized (missing or invalid token)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing access token."
  }
}

HTTP 403 — Forbidden (token lacks required scope)

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient scope."
  }
}

3. Endpoint Overview

3.1 Payout Management

3.2 Payout Settings

4. Payout Status Lifecycle

                    ┌──────────┐
                    │ Pending  │
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
        ┌──────────┐  ┌─────────┐  ┌────────┐
        │Processing│  │Completed│  │ Failed │
        └────┬─────┘  └─────────┘  └────────┘
             │
        ┌────┼────┐
        ▼         ▼
  ┌─────────┐  ┌────────┐
  │Completed│  │ Failed │
  └─────────┘  └────────┘

Valid transitions:

Invalid transitions return HTTP 409 with error code INVALID_STATUS.

5. Detailed Endpoint Specifications

5.1 List Payouts — GET /v1/payouts

Scope: payouts:read

Query Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 42,
        "affiliate": {
          "id": 7,
          "name": "Jane Smith",
          "referral_code": "JANE2026"
        },
        "amount": "250.00",
        "currency": "USD",
        "method": "bank_transfer",
        "status": "pending",
        "period_start": "2026-04-01",
        "period_end": "2026-04-30",
        "reference": null,
        "paid_at": null,
        "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "created_at": "2026-05-01T00:00:00.000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 1,
      "last_page": 1
    }
  }
}

Notes:

• affiliate is loaded from the affiliate’s user record. Contains id, name, and referral_code.
• method is extracted from the affiliate’s payment details. May be null if not set.
• batch_id groups payouts generated together by the automated scheduler. May be null for manual payouts.
• All monetary values are strings with 2 decimal places.
• Results are ordered by created_at DESC.

5.2 Get Payout Stats — GET /v1/payouts/stats

Scope: payouts:read

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "total_pending_amount": 1250.00,
    "total_pending_count": 5,
    "completed_this_month": 3400.00,
    "failed_count": 1,
    "pending_requests_count": 2
  }
}

Field descriptions:

5.3 Get Payout Detail — GET /v1/payouts/{id}

Scope: payouts:read

Path Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 42,
    "affiliate": {
      "id": 7,
      "name": "Jane Smith",
      "referral_code": "JANE2026"
    },
    "amount": "250.00",
    "currency": "USD",
    "method": "bank_transfer",
    "status": "completed",
    "period_start": "2026-04-01",
    "period_end": "2026-04-30",
    "reference": "TXN-12345",
    "paid_at": "2026-05-02T14:30:00.000Z",
    "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-05-01T00:00:00.000Z",
    "notes": "Paid via bank transfer",
    "updated_at": "2026-05-02T14:30:00.000Z",
    "payout_request": {
      "id": 10,
      "requested_amount": "250.00",
      "status": "approved",
      "notes": "Need early payout for expenses",
      "created_at": "2026-04-28T10:00:00.000Z"
    }
  }
}

Notes:

• Detail view returns additional fields not in the list: notes, updated_at, and linked payout_request.
• payout_request is present only if this payout was created from an affiliate’s early payout request. Otherwise omitted.

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Payout not found."
  }
}

5.4 List Payout Requests — GET /v1/payouts/requests

Scope: payouts:read

Query Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 10,
        "affiliate": {
          "id": 7,
          "name": "Jane Smith",
          "referral_code": "JANE2026"
        },
        "requested_amount": "250.00",
        "notes": "Need early payout for expenses",
        "status": "pending",
        "rejection_reason": null,
        "payout_id": null,
        "reviewed_at": null,
        "created_at": "2026-04-28T10:00:00.000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 1,
      "last_page": 1
    }
  }
}

Notes:

• payout_id is populated after the request is approved and a payout is created.
• rejection_reason is populated only for rejected requests.
• reviewed_at is the timestamp when the request was approved or rejected.

5.5 Export Payouts CSV — GET /v1/payouts/export

Scope: payouts:read Throttle: 30/min (heavy operation)

Query Parameters

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="payouts-export-2026-05-07.csv"

Affiliate,Email,Amount,Currency,Method,Status,Period Start,Period End,Reference,Paid At,Created At
Jane Smith,jane@example.com,250.00,USD,bank_transfer,completed,2026-04-01,2026-04-30,TXN-12345,2026-05-02 14:30:00,2026-05-01 00:00:00

5.6 Download Payout Statement — GET /v1/payouts/{id}/statement

Scope: payouts:read Throttle: 30/min (PDF generation)

Path Parameters

Success Response — HTTP 200

Content-Type: application/pdf Content-Disposition: attachment; filename="payout-statement-42.pdf"

Returns a PDF document containing:

• Payout details (amount, currency, period, reference)
• Conversions included in the payout period
• Conversion count, total order value, total commission

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Payout not found."
  }
}

5.7 Mark Payout as Processing — POST /v1/payouts/{id}/processing

Scope: payouts:write

Path Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout marked as processing.",
  "data": {
    "id": 42,
    "affiliate": { "id": 7, "name": "Jane Smith", "referral_code": "JANE2026" },
    "amount": "250.00",
    "currency": "USD",
    "method": "bank_transfer",
    "status": "processing",
    "period_start": "2026-04-01",
    "period_end": "2026-04-30",
    "reference": null,
    "paid_at": null,
    "batch_id": null,
    "created_at": "2026-05-01T00:00:00.000Z"
  }
}

Error — HTTP 409

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Cannot mark payout #42 as processing: current status is completed."
  }
}

5.8 Mark Payout as Completed — POST /v1/payouts/{id}/complete

Scope: payouts:write

Path Parameters

Body Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout marked as completed.",
  "data": {
    "id": 42,
    "status": "completed",
    "reference": "TXN-12345",
    "paid_at": "2026-05-07T14:30:00.000Z",
    "..."
  }
}

Side effect: Sends a PayoutCompletedNotification email to the affiliate.

Error — HTTP 409

Same as 5.7 — returned when current status is completed or failed.

5.9 Mark Payout as Failed — POST /v1/payouts/{id}/fail

Scope: payouts:write

Body Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout marked as failed.",
  "data": {
    "id": 42,
    "status": "failed",
    "..."
  }
}

Side effect: Sends a PayoutFailedNotification email to the affiliate.

5.10 Bulk Mark as Processing — POST /v1/payouts/bulk-processing

Scope: payouts:write

Body Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "3 payout(s) marked as processing.",
  "data": {
    "processed_count": 3,
    "requested_count": 5,
    "skipped_count": 2
  }
}

Notes:

• Only pending payouts are transitioned. Non-pending IDs are silently skipped.
• skipped_count = requested_count - processed_count.

5.11 Bulk Mark as Completed — POST /v1/payouts/bulk-complete

Scope: payouts:write

Body Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "3 payout(s) marked as completed.",
  "data": {
    "completed_count": 3,
    "requested_count": 3,
    "skipped_count": 0
  }
}

Notes:

• Only pending and processing payouts are transitioned. Others are skipped.
• The reference is applied to all completed payouts in the batch.

5.12 Approve Payout Request — POST /v1/payouts/requests/{id}/approve

Scope: payouts:write

Path Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout request approved.",
  "data": {
    "payout_request": {
      "id": 10,
      "affiliate": { "id": 7, "name": "Jane Smith", "referral_code": "JANE2026" },
      "requested_amount": "250.00",
      "status": "approved",
      "payout_id": 42,
      "reviewed_at": "2026-05-07T14:30:00.000Z",
      "created_at": "2026-04-28T10:00:00.000Z"
    },
    "payout": {
      "id": 42,
      "amount": "250.00",
      "currency": "USD",
      "status": "pending",
      "created_at": "2026-05-07T14:30:00.000Z"
    }
  }
}

Side effects:

• Creates a new pending payout linked to the request.
• Sends a PayoutRequestApprovedNotification email to the affiliate.

Error — HTTP 409

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Cannot approve request: current status is approved."
  }
}

5.13 Reject Payout Request — POST /v1/payouts/requests/{id}/reject

Scope: payouts:write

Path Parameters

Body Parameters

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout request rejected.",
  "data": {
    "id": 10,
    "affiliate": { "id": 7, "name": "Jane Smith", "referral_code": "JANE2026" },
    "requested_amount": "250.00",
    "status": "rejected",
    "rejection_reason": "Insufficient documentation provided.",
    "reviewed_at": "2026-05-07T14:30:00.000Z",
    "created_at": "2026-04-28T10:00:00.000Z"
  }
}

Side effect: Sends a PayoutRequestRejectedNotification email to the affiliate.

Validation Error — HTTP 422

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "reason": ["The reason field is required."]
    }
  }
}

6. Payout Settings Endpoints

6.1 Get Payout Settings — GET /v1/settings/payouts

Scope: settings:read

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "payout_frequency": "monthly",
    "payout_day": 15,
    "min_payout": "100.00",
    "currency": "USD",
    "allow_early_requests": true,
    "auto_create_payouts": true,
    "next_payout_date": "2026-06-15"
  }
}

Field descriptions:

6.2 Update Payout Settings — PUT /v1/settings/payouts

Scope: settings:write

Body Parameters

Note: payout_day max depends on payout_frequency:

• Weekly: max is 7 (ISO day of week: 1=Monday, 7=Sunday)
• Monthly: max is 31 (capped to actual days in month during generation)

Success Response — HTTP 200

{
  "success": true,
  "message": "Payout settings updated.",
  "data": {
    "payout_frequency": "weekly",
    "payout_day": 5,
    "min_payout": "25.00",
    "currency": "USD",
    "allow_early_requests": true,
    "auto_create_payouts": false,
    "next_payout_date": null
  }
}

7. Database Schema

7.1 payouts Table

Indexes: (business_id, affiliate_id), (business_id, paid_at), (business_id, status), BRIN (created_at).

7.2 payout_requests Table

Indexes: (business_id, affiliate_id), (business_id, status).

7.3 business_payout_settings Table

8. Notification Side Effects

Write operations trigger email notifications to affiliates and business owners:

All notifications are queued (implement ShouldQueue) and sent via the mail channel.

9. Security Considerations

10. Data Flow

External Client
    │
    ▼
┌─────────────────────────────────────────────────┐
│  API Domain (api.token middleware)               │
│  ├── Validates Bearer token                     │
│  ├── Resolves Business from token               │
│  ├── Enforces scope (payouts:read/write)        │
│  └── Sets request->attributes->business         │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  PayoutApiController (extends BaseApiController)│
│  ├── Validates input via FormRequest            │
│  ├── Delegates to PayoutService                 │
│  ├── Formats response via formatPayout()        │
│  └── Returns ApiResponse envelope               │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  PayoutService (EXISTING)                       │
│  ├── businessPayouts() → paginated query        │
│  ├── businessPayoutStats() → aggregated stats   │
│  ├── markProcessing/Completed/Failed()          │
│  ├── bulkMarkProcessing/Completed()             │
│  ├── approveRequest()/rejectRequest()           │
│  └── AuditService::log() → audit trail          │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  PostgreSQL — payouts, payout_requests,         │
│  business_payout_settings tables                │
│  (scoped by business_id, indexed)               │
└─────────────────────────────────────────────────┘

11. Implementation Files

Created

Modified

12. Test Coverage

29 tests, 133 assertions — all passing.