Update Payment

Overview

Update an existing payment record. Useful for corrections like changing the amount or channel.

Path

PATCH /api/v1/payments/{id}

Path parameter: id (integer, required) - The unique ID of the payment.

Query Parameters

None.

Request Headers

Content-Type: application/json
Authorization: Bearer <token> (OAuth 2.0 token)

Request Body

Required. JSON object with fields to update (partial updates supported).

Request Body Schema

{
  "payment": {
    "invoice_id": integer (optional),
    "amount": string|number (optional),
    "reference": string (optional),
    "channel": string (optional),
    "paid_at": string (optional, ISO 8601 datetime or date string)
  }
}

Example Request Body

{
  "payment": {
    "invoice_id": "100",
    "amount": "350",
    "reference": "Payment 123",
    "channel": "cash",
    "paid_at": "12 Oct 2025"
  }
}

Response

Success (200 OK)

Returns the updated payment object.

Response Body Schema

Same as GET /api/v1/payments/{id}.

Example Response

{
  "data": {
    "id": 29,
    "reference": "Payment 123",
    "invoice_id": 100,
    "channel": "cash",
    "amount": {
      "cents": 35000,
      "currency_iso": "USD"
    },
    "paid_at": "2025-10-12T00:00:00.000Z",
    "emailed_at": "2025-08-28T18:55:51.169Z",
    "created_at": "2025-08-28T18:55:22.584Z",
    "updated_at": "2025-10-21T04:41:29.995Z",
    "url": "http://localhost:3000/api/v1/payments/29.json"
  }
}

Errors

Status Code	Description	Example Body
401 Unauthorized	Invalid or missing token.	`{"error": "Unauthorized"}`
403 Forbidden	Insufficient permissions.	`{"error": "Forbidden"}`
404 Not Found	Payment not found.	`{"error": "Payment not found"}`
422 Unprocessable Entity	Invalid data (e.g., amount <= 0).	`{"errors": {"amount": ["must be greater than 0"]}}`
500 Internal Server Error	Server error.	`{"error": "Internal Server Error"}`

Usage Notes

Updating the amount recalculates the invoice balance.
Idempotent: Only provided fields are updated.
Triggers events for invoice updates if amount changes.

We are using cookies to improve your experience!