June 10, 2024

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

{
    "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:

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

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

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

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

{
  "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).