Skip to main content

Payouts API

This document covers user payout requests, processing statuses, and fee/tax breakdowns.

Enums​

  • ProcessingStatus: NOT_REQUESTED | REQUESTED | PROCESSING | COMPLETED | FAILED
  • PayoutStatus: PENDING | PAID | FAILED

Model: Payout​

Fields (selected):

  • seller (string): User ID requesting payout.
  • fulfillment (ObjectId | null): Linked fulfillment for tournament product payouts (optional).
  • tournament (ObjectId | null): Linked tournament (optional).
  • product (ObjectId | null): Linked product (optional).
  • currency (string): e.g., INR.
  • grossAmount (number): Requested amount.
  • platformFeePercent (number): Platform fee percentage (from business config).
  • processingFeeFlat (number): Flat processing fee (INR).
  • platformFeeAmount (number): Computed fee from percentage.
  • gstPercent (number): GST percent applied to platform fee.
  • gstAmount (number): GST amount computed from platform fee.
  • totalFees (number): Sum of applicable fees.
  • netAmount (number): grossAmount - totalFees (not negative).
  • status (PayoutStatus): Logical payout status.
  • processingStatus (ProcessingStatus): Operational processing state.
  • invoice (optional): Generated by admin on completion.

User Endpoints​

  1. POST /api/v1/payouts/request
  • Auth: Bearer required.
  • Body options:
    • Direct withdrawal: \{ amount: number \}
    • Tournament payout (legacy): \{ fulfillmentId: string \}
  • Behavior:
    • Validates amount > 0 for direct withdrawals.
    • Uses BusinessConfig (platformRate, gstRate) to compute fees; includes a flat processing fee of ₹99.
    • Creates a Payout with status='PENDING' and processingStatus='REQUESTED'.
    • For fulfillment-based requests, requires receiver confirmation and links the Payout to the fulfillment.
  • Response: Created payout document.
  1. GET /api/v1/payouts/taxes?amount=1234
  • Auth: Public.
  • Query: amount (number, required)
  • Response: Array of fee items with shape \{ cut, name, amount \} where:
    • cut: PERCENT or FLAT
    • name: label (e.g., Platform Fee (15%))
    • amount: computed fee in INR

Example response:

[
  { "cut": "PERCENT", "name": "Platform Fee (15%)", "amount": 150 },
  { "cut": "PERCENT", "name": "GST on Platform (18%)", "amount": 27 },
  { "cut": "FLAT", "name": "Processing Fee", "amount": 99 }
]

Admin Processing​

  • Admin processes payout from Order Details or Payouts list.
  • When processed, the system:
    • Finalizes amounts, generates invoice, and sets status='PAID' and processingStatus='COMPLETED'.
    • Links payout to fulfillment if applicable.

Notes​

  • Platform fee percentage and GST come from BusinessConfig and can be updated via Admin.
  • fulfillment, tournament, and product are optional to support direct withdrawals.
  • Admin UI shows both status and processingStatus.