# June 10, 2024 

** The June 10, 2024 Karbon API release includes a updates for customers using Karbon Billing, including a new API endpoint to make Manual Payments on an Invoice and a new Webhook subscription type for Invoice status changes. **
---

## ManualPayments

### POST ManualPayments
Endpoint: `https://api.karbonhq.com/v3/ManualPayments`

When used with the `POST` method, this endpoint enables a Manual Payment to be created against an Invoice.

Refer to the [Manual Payments API documentation](https://karbonhq.github.io/karbon-api-reference/#post-/v3/ManualPayments) for a full example of the response from this endpoint.

### Example use case
A payment is taken for an invoice outside of Karbon, a manual payment is created to ensure the outstanding invoice balance is correct and reporting in Karbon is accurate.

You need:
* an `InvoiceKey` for an invoice that has the status `AwaitingPayment` - e.g. `tnl31HQDzRS`
* a payment date that is on or after the invoice date and on or before the current date
* a payment amount that is less or equal to the amount owing on the invoice
* an optional reference to include with the payment record

Make a call to `https://api.karbonhq.com/v3/ManualPayments` with the request payload:

```JSON
{
    "InvoiceKey" : "tnl31HQDzRS",
    "PaymentMethod" : "Cash",
    "PaymentDate" : "2024-06-10",
    "TotalAmount" : 110.10,
    "Reference" : "Partial payment in Cash"
}
```

This will create a manual payment and return the response with HTTP `201` status code:

```JSON
{
    "@odata.context": "https://api.karbonhq.com/v3/$metadata#ManualPayments/$entity",
    "InvoiceKey": "tnl31HQDzRS",
    "PaymentMethod": "Cash",
    "PaymentDate": "2024-06-10T00:00:00Z",
    "TotalAmount" : 110.10,
    "Reference" : "Partial payment in Cash",
    "PaymentProcessingKey": "8ywNzh9cTgm"
}
```

---

### Notes:
At the time of writing valid values for PaymentMethod are: `Bank Transfer`, `Direct Debit`, `Credit Card Online`, `Credit Card Office`, `Check`, `Cash` or `Other`.

---

## Invoice Webhook Subscription

### POST, GET and DELETE WebhookSubscriptions
Endpoint: `https://api.karbonhq.com/v3/WebhookSubscriptions`

The `WebhookSubscriptions` endpoints now allow subscriptions with the type `Invoice` to be used. New subscriptions created with the `Invoice` type will dispatch a notification to the subscribed URL when an Invoice has been sent to a client and the status of an invoice has changed to `AwaitingPayment`, `Paid`, `Voided`.

The following actions will cause a webhook to be triggered, though the status may be the same as a previous instance:
* Partial payments on an invoice
* Moving an invoice between billing runs

Refer to the [Webhook Subscriptions API documentation](https://karbonhq.github.io/karbon-api-reference/#tag--Webhook-Subscriptions) for a full example of the response from this endpoint.

### Example use case
Your firm manages a centralised AR ledger and requires all invoices from Karbon Billing to be recorded in this ledger as soon as they are sent to a client, paid by the client or voided.

In order to receive a webhook notification of an Invoice being sent, paid or voided, make a call to `https://api.karbonhq.com/v3/WebhookSubscriptions` with the request payload:

```JSON
{
    "TargetUrl": "https://example.com/webhook-notifications",
    "WebhookType": "Invoice"
}
```

This will create a new Webhook Subscription for Invoices and return the response:

```JSON
{
    "@odata.context": "https://api-dev.karbonhq.com/v3/$metadata#WebhookSubscriptions/$entity",
    "TargetUrl": "https://example.com/webhook-notifications",
    "WebhookType": "Invoice"
}
```

Changing the status of an Invoice from within Karbon (e.g. voiding the invoice) or by using the ManualPayments endpoint (above) to completely pay off the invoice `CkyyMTjH6wq` will result in a webhook message with the body:

```JSON
{
  "ResourcePermaKey": "CkyyMTjH6wq",
  "ResourceType": "Invoice",
  "ActionType": "Paid"
}
```

---

### Note
It is only possible to have one subscription per type of `WebhookSubscription` (e.g. `Contact`, `Invoice`, `Note`, `User` or `Work`).