Payments

Records money you received outside Chargetree's payment pages -- cash, a bank transfer, a card terminal or a gift card -- against one of your invoices. The invoice's amount_paid, amount_due and status are updated straight away: a payment that leaves a balance makes it PARTIALLY_PAID (or OVERDUE once past its due date), and one that clears the balance makes it PAID.

The payment is added to the invoice's history, attributed to your API key, and the invoice.payment_recorded webhook fires. No receipt is emailed to the contact.

If the invoice is linked to Xero, Chargetree also records the payment there, using the bank account chosen for that payment method in Settings > Payments. This is best-effort: if Xero is not connected, no bank account is chosen, or Xero refuses the payment, the payment is still recorded in Chargetree and the response shows xero_synced: false with the reason in xero_error.

Only finalised invoices that still have money owing can take a payment. Drafts, cancelled invoices and paid invoices are refused, and so is any amount larger than the outstanding balance. Scheduled invoices (finalised, waiting to be emailed on a future date) do accept payments, so a customer can pay before the invoice is sent.

This endpoint honours the Idempotency-Key header, so a retried call after a dropped connection will not record the payment twice.

Path Parameters

Header Parameters

Response Body

curl -X POST "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/payments" \  -H "Idempotency-Key: 0f2a5f1e-9f1a-4e0c-9a4e-2a9b7d1f6c33" \  -H "Content-Type: application/json" \  -d '{    "amount": 250,    "method": "bank_transfer",    "paid_on": "2026-10-02",    "reference": "EFT 88213 Acme Pty Ltd"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "invoice_number": "string",  "status": "DRAFT",  "is_draft": true,  "contact": null,  "invoice_date": "2019-08-24",  "due_date": "2019-08-24",  "currency": "string",  "line_amount_types": "string",  "sub_total": 0,  "tax_total": 0,  "total": 0,  "amount_paid": 0,  "amount_due": 0,  "line_items": [    {      "id": "string",      "description": "string",      "quantity": 0,      "unit_amount": 0,      "tax_rate": 0,      "tax_amount": 0,      "line_amount": 0    }  ],  "payments": [    {      "id": "string",      "amount": 0,      "currency": "string",      "received_at": "2019-08-24T14:15:22Z",      "paid_on": "2019-08-24",      "method": "string",      "reference": "string",      "recorded_by": "user"    }  ],  "reference": "string",  "notes": "string",  "staff": "string",  "is_editable": true,  "sent_to_contact": true,  "last_sent_at": "2019-08-24T14:15:22Z",  "send_count": 0,  "pay_url": "string",  "xero_invoice_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "payment": {    "id": "string",    "amount": 0,    "currency": "string",    "received_at": "2019-08-24T14:15:22Z",    "paid_on": "2019-08-24",    "method": "string",    "reference": "string",    "recorded_by": "user"  },  "xero_synced": true,  "xero_error": "string"}