Payments API ============ The Payments API provides endpoints for managing payouts, bank accounts, and financial transactions. App Endpoints ------------- Get Payouts ~~~~~~~~~~~ Retrieve user's payout history and pending payouts. .. http:post:: /api/get/payouts/ **Request Body:** .. code-block:: text page=1 limit=20 status=all **Response:** .. code-block:: json { "payouts": [ { "id": 123, "amount": 500, "currency": "USD", "status": "completed", "method": "bank_transfer", "bank_account": { "id": 456, "bank_name": "Chase Bank", "account_number": "****1234", "account_type": "checking" }, "requested_at": "2024-08-01T10:00:00Z", "processed_at": "2024-08-02T15:30:00Z", "reference": "PAY-2024-001" }, { "id": 124, "amount": 300, "currency": "USD", "status": "pending", "method": "paypal", "paypal_email": "user@example.com", "requested_at": "2024-08-03T09:00:00Z", "reference": "PAY-2024-002" } ], "total": 50, "page": 1, "limit": 20, "summary": { "total_earned": 5000, "total_paid": 4500, "pending_amount": 500, "currency": "USD" } } Update Bank Account ~~~~~~~~~~~~~~~~~~ Update user's bank account information. .. http:post:: /api/update/bank-account/ **Request Body:** .. code-block:: text bank_name=Wells Fargo account_number=1234567890 routing_number=021000021 account_type=checking account_holder_name=John Doe **Response:** .. code-block:: json { "status": "success", "message": "Bank account updated successfully", "bank_account_id": 457 } Payout Actions ~~~~~~~~~~~~~~ Request Payout ^^^^^^^^^^^^^ Request a new payout. .. http:post:: /api/action/payout/ **Request Body:** .. code-block:: text amount=500 method=bank_transfer bank_account_id=456 **Response:** .. code-block:: json { "status": "success", "message": "Payout request submitted successfully", "payout_id": 125, "reference": "PAY-2024-003", "estimated_processing_time": "2-3 business days" } Cancel Payout ^^^^^^^^^^^^ Cancel a pending payout. .. http:post:: /api/action/payout/cancel/ **Request Body:** .. code-block:: text payout_id=125 **Response:** .. code-block:: json { "status": "success", "message": "Payout cancelled successfully" } Backend Endpoints ----------------- Payout Management ~~~~~~~~~~~~~~~~~ Get All Payouts ^^^^^^^^^^^^^^ Retrieve all payouts for administrative purposes. .. http:post:: /api/payouts/all/ **Request Body:** .. code-block:: text date_from=2024-01-01 date_to=2024-12-31 status=all page=1 limit=50 **Response:** .. code-block:: json { "payouts": [ { "id": 123, "user_id": 456, "user_name": "John Doe", "user_email": "john@example.com", "amount": 500, "currency": "USD", "status": "completed", "method": "bank_transfer", "bank_account": { "bank_name": "Chase Bank", "account_number": "****1234" }, "requested_at": "2024-08-01T10:00:00Z", "processed_at": "2024-08-02T15:30:00Z", "reference": "PAY-2024-001" } ], "total": 100, "page": 1, "limit": 50, "summary": { "total_amount": 50000, "completed_amount": 45000, "pending_amount": 5000, "currency": "USD" } } Process Payout ^^^^^^^^^^^^^ Process a pending payout. .. http:post:: /api/payouts/process/ **Request Body:** .. code-block:: text payout_id=125 transaction_id=TXN-2024-001 notes=Processed via bank transfer **Response:** .. code-block:: json { "status": "success", "message": "Payout processed successfully", "processed_at": "2024-08-04T10:00:00Z" } Reject Payout ^^^^^^^^^^^^ Reject a payout request. .. http:post:: /api/payouts/reject/ **Request Body:** .. code-block:: text payout_id=125 reason=Insufficient funds notes=User balance is below minimum payout threshold **Response:** .. code-block:: json { "status": "success", "message": "Payout rejected successfully" } Financial Statistics ~~~~~~~~~~~~~~~~~~~ Payout Statistics ^^^^^^^^^^^^^^^^ Get payout statistics. .. http:post:: /api/payouts/stats/ **Request Body:** .. code-block:: text date_from=2024-01-01 date_to=2024-12-31 **Response:** .. code-block:: json { "total_payouts": 100, "total_amount": 50000, "average_payout": 500, "currency": "USD", "by_status": { "completed": 80, "pending": 15, "rejected": 5 }, "by_method": { "bank_transfer": 60, "paypal": 30, "stripe": 10 } } User Balance ^^^^^^^^^^^ Get user balance information. .. http:post:: /api/user/balance/ **Request Body:** .. code-block:: text user_id=456 **Response:** .. code-block:: json { "user_id": 456, "available_balance": 750, "pending_balance": 250, "total_earned": 5000, "total_paid": 4000, "currency": "USD", "minimum_payout": 50 } Bank Account Management ~~~~~~~~~~~~~~~~~~~~~~ Get Bank Accounts ^^^^^^^^^^^^^^^^ Retrieve user's bank accounts. .. http:post:: /api/bank-accounts/ **Request Body:** .. code-block:: text user_id=456 **Response:** .. code-block:: json { "bank_accounts": [ { "id": 456, "bank_name": "Chase Bank", "account_number": "****1234", "routing_number": "****0021", "account_type": "checking", "account_holder_name": "John Doe", "is_primary": true, "verified": true, "created_at": "2024-01-01T00:00:00Z" } ] } Verify Bank Account ^^^^^^^^^^^^^^^^^^ Verify a bank account. .. http:post:: /api/bank-accounts/verify/ **Request Body:** .. code-block:: text bank_account_id=456 verification_amount_1=0.32 verification_amount_2=0.45 **Response:** .. code-block:: json { "status": "success", "message": "Bank account verified successfully" } Delete Bank Account ^^^^^^^^^^^^^^^^^^ Delete a bank account. .. http:post:: /api/bank-accounts/delete/ **Request Body:** .. code-block:: text bank_account_id=456 **Response:** .. code-block:: json { "status": "success", "message": "Bank account deleted successfully" } Payment Methods ~~~~~~~~~~~~~~~ Get Payment Methods ^^^^^^^^^^^^^^^^^^ Retrieve available payment methods. .. http:post:: /api/payment-methods/ **Response:** .. code-block:: json { "payment_methods": [ { "id": "bank_transfer", "name": "Bank Transfer", "description": "Direct bank transfer", "processing_time": "2-3 business days", "minimum_amount": 50, "maximum_amount": 10000, "fees": 0 }, { "id": "paypal", "name": "PayPal", "description": "PayPal transfer", "processing_time": "1-2 business days", "minimum_amount": 10, "maximum_amount": 5000, "fees": 2.9 }, { "id": "stripe", "name": "Stripe", "description": "Stripe transfer", "processing_time": "1-2 business days", "minimum_amount": 10, "maximum_amount": 5000, "fees": 2.9 } ] } Data Models ----------- Payout ~~~~~~ .. code-block:: json { "id": 123, "user_id": 456, "amount": 500, "currency": "USD", "status": "completed", "method": "bank_transfer", "bank_account": { "id": 456, "bank_name": "Chase Bank", "account_number": "****1234", "routing_number": "****0021", "account_type": "checking", "account_holder_name": "John Doe" }, "paypal_email": null, "stripe_account": null, "requested_at": "2024-08-01T10:00:00Z", "processed_at": "2024-08-02T15:30:00Z", "cancelled_at": null, "reference": "PAY-2024-001", "transaction_id": "TXN-2024-001", "notes": "Processed via bank transfer", "fees": 0, "net_amount": 500 } Bank Account ~~~~~~~~~~~~ .. code-block:: json { "id": 456, "user_id": 456, "bank_name": "Chase Bank", "account_number": "****1234", "routing_number": "****0021", "account_type": "checking", "account_holder_name": "John Doe", "is_primary": true, "verified": true, "verification_status": "verified", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-08-01T10:00:00Z" } User Balance ~~~~~~~~~~~~ .. code-block:: json { "user_id": 456, "available_balance": 750, "pending_balance": 250, "total_earned": 5000, "total_paid": 4000, "currency": "USD", "minimum_payout": 50, "last_updated": "2024-08-01T10:00:00Z" } Payout Status Values ------------------- - **pending**: Payout request submitted but not yet processed - **processing**: Payout is being processed - **completed**: Payout has been successfully processed - **rejected**: Payout request has been rejected - **cancelled**: Payout request has been cancelled by user - **failed**: Payout processing failed Payment Methods -------------- - **bank_transfer**: Direct bank transfer (ACH/Wire) - **paypal**: PayPal transfer - **stripe**: Stripe transfer - **check**: Physical check (if available) Error Responses -------------- Authentication Errors ~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "authentication_required", "message": "Authentication is required for this endpoint" } .. code-block:: json { "error": "insufficient_permissions", "message": "You don't have permission to access payout information" } Validation Errors ~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "validation_error", "message": "Invalid bank account number", "field": "account_number" } .. code-block:: json { "error": "validation_error", "message": "Amount must be greater than minimum payout amount", "field": "amount" } .. code-block:: json { "error": "validation_error", "message": "Invalid routing number", "field": "routing_number" } Business Logic Errors ~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "insufficient_balance", "message": "Insufficient balance for payout request" } .. code-block:: json { "error": "payout_limit_exceeded", "message": "Payout amount exceeds maximum limit" } .. code-block:: json { "error": "bank_account_not_verified", "message": "Bank account must be verified before payout" } .. code-block:: json { "error": "payout_already_processed", "message": "Payout has already been processed" } .. code-block:: json { "error": "payout_cannot_be_cancelled", "message": "Payout cannot be cancelled in current status" }