Payments Received

Payments received from customers, allocated against invoices or customer credit.

GET/api/v1/payments-received

List payments received

Scope: paymentsReceived.read

Parameters

Name	In	Type	Required	Description
`page`	query	number	Optional	1-based page number.
`limit`	query	number	Optional	Page size, max 200.
`q`	query	string	Optional	Free-text search on payment number or reference number.

Example request

curl "https://invoice.avscorp.in/api/v1/payments-received" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2pr0001000000000000001",
  "organizationId": "clx2org001000000000000001",
  "paymentNumber": "PR-2026-0044",
  "customerId": "clx2cus001000000000000001",
  "paymentDate": "2026-09-07T00:00:00.000Z",
  "mode": "BANK_TRANSFER",
  "referenceNumber": "UTR9988776655",
  "depositAccount": "HDFC Current A/C",
  "amount": 15340,
  "allocated": 15340,
  "openingBalanceApplied": 0,
  "currencyCode": "INR",
  "exchangeRate": 1,
  "razorpayPaymentId": null,
  "isRazorpayAuto": false,
  "notes": "Full settlement of INV-2026-0102",
  "createdBy": "clx2usr001000000000000001",
  "createdAt": "2026-09-07T11:00:00.000Z",
  "updatedAt": "2026-09-07T11:00:00.000Z"
}

Possible errors: unauthorized, insufficient_scope, forbidden

POST/api/v1/payments-received

Record a payment received

Scope: paymentsReceived.createSupports Idempotency-Key

Accepts an optional Idempotency-Key header. Sum of allocations + openingBalanceApplied must not exceed amount + tdsAmount. Optional tdsAmount / tdsSectionCode record TDS the customer deducted (it settles invoices like cash). Returns only { id }.

Request body

Field	Type	Required	Constraints
`customerId`	string	Required	min length 1
`paymentDate`	string	Required	—
`mode`	string	Optional	one of: CASH, BANK_TRANSFER, UPI, CARD, CHEQUE, RAZORPAY, OTHER; default "BANK_TRANSFER"
`referenceNumber`	any	Optional	—
`depositAccount`	any	Optional	—
`amount`	number	Required	—
`currencyCode`	string	Optional	min length 3; max length 3; default "INR"
`exchangeRate`	number	Optional	default 1
`notes`	any	Optional	—
`allocations`	array	Optional	default []
`openingBalanceApplied`	number	Optional	min 0; default 0
`tdsAmount`	number	Optional	min 0
`tdsSectionCode`	any	Optional	—

Example request

curl -X POST "https://invoice.avscorp.in/api/v1/payments-received" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "clx2cus001000000000000001",
  "paymentDate": "2026-09-07",
  "mode": "BANK_TRANSFER",
  "referenceNumber": "UTR9988776655",
  "amount": 15340,
  "allocations": [
    {
      "invoiceId": "clx2inv001000000000000001",
      "amount": 15340
    }
  ]
}'

Example response

JSON

{
  "id": "clx2pr0001000000000000001"
}

Possible errors: unauthorized, insufficient_scope, forbidden, validation_error

GET/api/v1/payments-received/{id}

Get a payment received

Scope: paymentsReceived.read

Includes allocations.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Payment ID.

Example request

curl "https://invoice.avscorp.in/api/v1/payments-received/clx2pr0001000000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2pr0001000000000000001",
  "organizationId": "clx2org001000000000000001",
  "paymentNumber": "PR-2026-0044",
  "customerId": "clx2cus001000000000000001",
  "paymentDate": "2026-09-07T00:00:00.000Z",
  "mode": "BANK_TRANSFER",
  "referenceNumber": "UTR9988776655",
  "depositAccount": "HDFC Current A/C",
  "amount": 15340,
  "allocated": 15340,
  "openingBalanceApplied": 0,
  "currencyCode": "INR",
  "exchangeRate": 1,
  "razorpayPaymentId": null,
  "isRazorpayAuto": false,
  "notes": "Full settlement of INV-2026-0102",
  "createdBy": "clx2usr001000000000000001",
  "createdAt": "2026-09-07T11:00:00.000Z",
  "updatedAt": "2026-09-07T11:00:00.000Z",
  "allocations": [
    {
      "id": "clx2pra001000000000000001",
      "organizationId": "clx2org001000000000000001",
      "paymentId": "clx2pr0001000000000000001",
      "invoiceId": "clx2inv001000000000000001",
      "customerAdjustmentId": null,
      "amount": 15340
    }
  ]
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found

DELETE/api/v1/payments-received/{id}

Delete a payment received

Scope: paymentsReceived.delete

Reverses allocations (and any opening-balance credit) in a transaction.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Payment ID.

Example request

curl -X DELETE "https://invoice.avscorp.in/api/v1/payments-received/clx2pr0001000000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "ok": true
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found