API Reference

Payouts API

Complete API reference for managing seller payouts, withdrawals, and transaction history.

Base URL

http://localhost:5000/api/payouts

Authentication

All payout endpoints require authentication. Include JWT token in header:

Authorization: Bearer YOUR_JWT_TOKEN

Only seller and admin roles can access payout endpoints.

GET /balance

Get current payout balance and earnings breakdown for authenticated seller.

Example Request

curl -X GET http://localhost:5000/api/payouts/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK)

{
  "success": true,
  "data": {
    "availableBalance": 45000,
    "pendingBalance": 5000,
    "totalEarnings": 150000,
    "totalWithdrawn": 100000,
    "currency": "INR",
    "minimumPayout": 500,
    "earnings": {
      "thisMonth": 15000,
      "lastMonth": 12000,
      "totalSales": 150
    },
    "bankAccount": {
      "isVerified": true,
      "accountNumber": "****3456",
      "ifsc": "SBIN0001234"
    }
  }
}

POST /request

Request a payout to registered bank account.

Request Body

Parameter	Type	Required	Description
`amount`	number	Yes	Amount to withdraw (min: 500)
`notes`	string	Optional	Optional notes for payout

Example Request

curl -X POST http://localhost:5000/api/payouts/request \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "notes": "Monthly payout"
  }'

Success Response (201 Created)

{
  "success": true,
  "message": "Payout request created successfully",
  "data": {
    "payoutId": "pyt_H8dN3K2mL9jP",
    "amount": 10000,
    "status": "processing",
    "estimatedArrival": "2026-02-10T10:30:00.000Z",
    "accountNumber": "****3456",
    "requestedAt": "2026-02-07T10:30:00.000Z"
  }
}

Error Responses

400 Insufficient Balance

{
  "success": false,
  "error": "Insufficient balance. Available: ₹8000"
}

400 Bank Account Not Verified

{
  "success": false,
  "error": "Bank account not verified. Please verify before requesting payout."
}

GET /history

Get paginated list of all payout transactions.

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	10	Items per page (max: 50)
`status`	string	all	processing, completed, failed

Example Request

curl -X GET "http://localhost:5000/api/payouts/history?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK)

{
  "success": true,
  "data": {
    "payouts": [
      {
        "id": "pyt_H8dN3K2mL9jP",
        "amount": 10000,
        "status": "completed",
        "accountNumber": "****3456",
        "requestedAt": "2026-02-05T10:30:00.000Z",
        "completedAt": "2026-02-07T08:15:00.000Z",
        "utr": "026207123456"
      },
      {
        "id": "pyt_J9kM5N3pQ2rS",
        "amount": 25000,
        "status": "processing",
        "accountNumber": "****3456",
        "requestedAt": "2026-02-07T10:30:00.000Z",
        "estimatedArrival": "2026-02-10T10:30:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 47,
      "itemsPerPage": 10
    }
  }
}

GET /:payoutId

Get detailed information about a specific payout.

Example Request

curl -X GET http://localhost:5000/api/payouts/pyt_H8dN3K2mL9jP \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "pyt_H8dN3K2mL9jP",
    "sellerId": "507f1f77bcf86cd799439011",
    "amount": 10000,
    "fee": 50,
    "netAmount": 9950,
    "status": "completed",
    "bankAccount": {
      "accountNumber": "****3456",
      "ifsc": "SBIN0001234",
      "accountHolder": "Swapnil Shelke"
    },
    "requestedAt": "2026-02-05T10:30:00.000Z",
    "processedAt": "2026-02-05T11:00:00.000Z",
    "completedAt": "2026-02-07T08:15:00.000Z",
    "utr": "026207123456",
    "notes": "Monthly payout",
    "razorpayPayoutId": "pout_ABC123XYZ789"
  }
}

POST /:payoutId/cancel

Cancel a pending payout request (only if status is "processing").

Example Request

curl -X POST http://localhost:5000/api/payouts/pyt_J9kM5N3pQ2rS/cancel \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK)

{
  "success": true,
  "message": "Payout cancelled successfully",
  "data": {
    "payoutId": "pyt_J9kM5N3pQ2rS",
    "status": "cancelled",
    "refundedAmount": 25000
  }
}