Skip to main content

Record a partial payment

Entry. POST /v1/commerce/orders/:id/partial-payment → OrderPaymentService.recordPartialPayment.

Source: order-payment.service.ts.

Rules​

  • The order must exist and not be soft-deleted.
  • CANCELLED and CLOSED throw order.error.orderClosedOrCancelled.
  • Remaining balance is grandTotal (or orderTotal when grand total is null) minus paidAmount. Remaining of 0 or less throws order.error.orderAlreadyFullyPaid.
  • Amount must be greater than 0 (order.error.invalidPartialPaymentAmount) and must not exceed the remaining balance. The error string includes the rupee symbol and both amounts.
  • The new paid amount sets paymentStatus to PAID when it covers the grand total, otherwise PARTIALLY_PAID.

What is written​

Inside one transaction the service updates paidAmount and paymentStatus, and inserts OrderPaymentTransaction. The idempotency key is ppcod:{orderId}:{random UUID} generated on each call. A repeated HTTP request therefore gets a new key. A provider transaction id is stored only when dto.transactionId is non-empty after trim.

This path does not change orderStatus and does not enqueue order.confirmed. A payment hold that later moves the order to PENDING is a status change. Allocation on that transition is What an order status does to fulfillment.