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.
- POST /api/get/payouts/
Request Body:
page=1 limit=20 status=all
Response:
{ "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.
- POST /api/update/bank-account/
Request Body:
bank_name=Wells Fargo account_number=1234567890 routing_number=021000021 account_type=checking account_holder_name=John Doe
Response:
{ "status": "success", "message": "Bank account updated successfully", "bank_account_id": 457 }
Payout Actions
Request Payout
Request a new payout.
- POST /api/action/payout/
Request Body:
amount=500 method=bank_transfer bank_account_id=456
Response:
{ "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.
- POST /api/action/payout/cancel/
Request Body:
payout_id=125
Response:
{ "status": "success", "message": "Payout cancelled successfully" }
Backend Endpoints
Payout Management
Get All Payouts
Retrieve all payouts for administrative purposes.
- POST /api/payouts/all/
Request Body:
date_from=2024-01-01 date_to=2024-12-31 status=all page=1 limit=50
Response:
{ "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.
- POST /api/payouts/process/
Request Body:
payout_id=125 transaction_id=TXN-2024-001 notes=Processed via bank transfer
Response:
{ "status": "success", "message": "Payout processed successfully", "processed_at": "2024-08-04T10:00:00Z" }
Reject Payout
Reject a payout request.
- POST /api/payouts/reject/
Request Body:
payout_id=125 reason=Insufficient funds notes=User balance is below minimum payout threshold
Response:
{ "status": "success", "message": "Payout rejected successfully" }
Financial Statistics
Payout Statistics
Get payout statistics.
- POST /api/payouts/stats/
Request Body:
date_from=2024-01-01 date_to=2024-12-31
Response:
{ "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.
- POST /api/user/balance/
Request Body:
user_id=456
Response:
{ "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.
- POST /api/bank-accounts/
Request Body:
user_id=456
Response:
{ "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.
- POST /api/bank-accounts/verify/
Request Body:
bank_account_id=456 verification_amount_1=0.32 verification_amount_2=0.45
Response:
{ "status": "success", "message": "Bank account verified successfully" }
Delete Bank Account
Delete a bank account.
- POST /api/bank-accounts/delete/
Request Body:
bank_account_id=456
Response:
{ "status": "success", "message": "Bank account deleted successfully" }
Payment Methods
Get Payment Methods
Retrieve available payment methods.
- POST /api/payment-methods/
Response:
{ "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
{
"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
{
"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
{
"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
{
"error": "authentication_required",
"message": "Authentication is required for this endpoint"
}
{
"error": "insufficient_permissions",
"message": "You don't have permission to access payout information"
}
Validation Errors
{
"error": "validation_error",
"message": "Invalid bank account number",
"field": "account_number"
}
{
"error": "validation_error",
"message": "Amount must be greater than minimum payout amount",
"field": "amount"
}
{
"error": "validation_error",
"message": "Invalid routing number",
"field": "routing_number"
}
Business Logic Errors
{
"error": "insufficient_balance",
"message": "Insufficient balance for payout request"
}
{
"error": "payout_limit_exceeded",
"message": "Payout amount exceeds maximum limit"
}
{
"error": "bank_account_not_verified",
"message": "Bank account must be verified before payout"
}
{
"error": "payout_already_processed",
"message": "Payout has already been processed"
}
{
"error": "payout_cannot_be_cancelled",
"message": "Payout cannot be cancelled in current status"
}