Skip to main content

Payment Methods API

Store and retrieve payout details (multiple UPI and multiple bank accounts) for a user, with a configurable default payout method.

Base URL: /api/v1/payment-methods

Auth: All endpoints require Bearer auth.

Model​

PaymentMethod fields:

  • user (ObjectId ref User) — unique per user
  • upis (array of \{ _id, upi \})
  • bankAccounts (array of bank account objects)
    • accountNumber, ifsc, bankName, accountHolderName, branchName, branchDetails
  • defaultMethod (object or null) — \{ type: 'UPI'|'BANK', refId: string \}

Immutability:

  • Each UPI or bank account entry is append-only; edits create a new entry.
  • Entries include active (boolean), removedAt (timestamp, optional), createdAt and updatedAt.
  • Deleting a method is a soft delete (marks active=false, sets removedAt), history is preserved.

Notes:

  • Multiple UPIs and multiple bank accounts are supported per user.
  • The newest entries are appended to the array; default is set via defaultMethod.

GET /me​

Returns the current user’s payment methods (or null if not set).

Response:

200 OK
{ "data": {
  "_id": "...",
  "user": "...",
  "upis": [ { "_id": "...", "upi": "user@upi" } ],
  "bankAccounts": [ { "_id": "...", "ifsc": "HDFC0001234", "accountNumber": "1234567890", "branchName": "Andheri West" } ],
  "defaultMethod": { "type": "UPI", "refId": "..." },
  "createdAt": "...",
  "updatedAt": "..."
} }

PUT /me (compat append)​

Append a UPI or bank account in a single call; optionally set as default.

Body (any subset):

{ "upi": "user@upi", "makeDefault": true }
{ "bankDetails": { "accountNumber": "1234", "ifsc": "HDFC0001234" }, "makeDefault": true }

Response: 200 OK \{ "data": \{ ...PaymentMethod \} \}

POST /upi​

Add a UPI handle (append-only). If a previous UPI is changed, add a new one; old ones remain in history.

  • Body: \{ "upi": "user@upi", "makeDefault?": boolean \}
  • Response: 201 Created \{ id, upi, default \}

POST /bank​

Add a bank account (append-only). If details change, add a new entry; old ones remain in history.

  • Body: \{ accountNumber?, ifsc?, bankName?, accountHolderName?, branchName?, branchDetails?, makeDefault? \}
  • Response: 201 Created \{ id, default \}

POST /default​

Set the default payout method.

  • Body: \{ "type": "UPI" | "BANK", "id": "<subdoc id>" \}
  • Response: 200 OK \{ ok: true \}

DELETE /upi/:id​

Soft delete a UPI by id (marks inactive). If it was default, default becomes null.

DELETE /bank/:id​

Soft delete a bank account by id (marks inactive). If it was default, default becomes null.