June 10, 2024

ManualPayments

POST ManualPayments

Endpoint:

When used with the

method, this endpoint enables a Manual Payment to be created against an Invoice.

Refer to the Manual Payments API documentation 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
  JSONCopyCopied!

  InvoiceKey
  for an invoice that has the status
  JSONCopyCopied!

  AwaitingPayment
  - e.g.
  JSONCopyCopied!

  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

with the request payload:

JSONCopyCopied!
{
    "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

status code:

JSONCopyCopied!
{
    "@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:

, , , , , or .

---

Invoice Webhook Subscription

POST, GET and DELETE WebhookSubscriptions

Endpoint:

The

endpoints now allow subscriptions with the type to be used. New subscriptions created with the 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 , , .

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 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

with the request payload:

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

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

JSONCopyCopied!
{
    "@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

will result in a webhook message with the body:

JSONCopyCopied!
{
  "ResourcePermaKey": "CkyyMTjH6wq",
  "ResourceType": "Invoice",
  "ActionType": "Paid"
}

---

Note

It is only possible to have one subscription per type of

(e.g. , , , or ).