Create new Payment

Overview

Create a new payment record associated with a specific invoice. This updates the invoice’s balance and status if fully paid.

Path

POST /api/v1/payments

Path Parameters

None.

Query Parameters

None.

Request Headers

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

Request Body

Required. JSON object with payment details.

Request Body Schema

{
  "payment": {
    "invoice_id": integer (required),
    "amount": string|number (required, e.g., "340" or 340.00; in major units),
    "reference": string (optional, custom reference),
    "channel": string (required, e.g., "cash", "card", "bank_transfer"),
    "paid_at": string (optional, ISO 8601 datetime or date string like "12 Oct 2025")
  }
}

Example Request Body

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

Response

Success (201 Created)

Returns the created payment object.

Response Body Schema

{
  "data": {
    "id": integer,
    "reference": string,
    "invoice_id": integer,
    "channel": string,
    "amount": {
      "cents": integer,
      "currency_iso": string
    },
    "paid_at": string (ISO 8601 datetime),
    "emailed_at": string|null (ISO 8601 datetime),
    "created_at": string (ISO 8601 datetime),
    "updated_at": string (ISO 8601 datetime),
    "url": string (full API URL to the payment)
  }
}

Example Response

{
  "data": {
    "id": 37,
    "reference": "Payment 123",
    "invoice_id": 100,
    "channel": "cash",
    "amount": {
      "cents": 34000,
      "currency_iso": "USD"
    },
    "paid_at": "2025-10-12T00:00:00.000Z",
    "emailed_at": null,
    "created_at": "2025-10-21T04:41:11.901Z",
    "updated_at": "2025-10-21T04:41:11.901Z",
    "url": "http://localhost:3000/api/v1/payments/37.json"
  }
}

Errors

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

Usage Notes

The amount is converted to cents internally based on the invoice’s currency.
If the payment overpays the invoice, it will still be recorded; handle refunds separately.
paid_at defaults to now if omitted.
Triggers invoice status updates and optional email notifications.

We are using cookies to improve your experience!