We are happy to announce our new item payments extension for the claims API. This feature enables partial payments of claims while improving the overall claim and payment related API experience. There are a couple of things to look at and I would like to walk you through the changes in more detail.
This feature might break your existing API integration. Please read this article carefully to understand the implications. It is planned to enforce its activation. Until then, it is disabled and can be enabled on request. Please reach out to your account manager to align on this topic. You can test the new behavior safely in our demo environment.
About
Over the past few years we gained extensive experience integrating various clients from different industries. While doing this exercise many times we noticed some recurring limitations, especially on the data synchronization aspects with the claims API model. In particular, the usage of the claim item model was not perfect, because it represented the outstanding balance of a given receivable only. There was no counterpart attached to the data model to represent the already paid claim amount. It was managed implicitly by mutating the individual item values according to most recent payments flows. The new item payments feature is finally addressing those limitations.
Data Model
The claim model has been extended with two new readonly fields:
total- Defines the total claim amount (money to be claimed, calculated as sum of item values)outstanding- Defines the claim open amount (money to be paid, calculated as sum of item outstanding amounts)
The claim item model has been extended with the outstanding field to complement the same view:
value- Defines the item amount (money to be claimed)outstanding- Defines the item open amount (money to be paid)
The outstanding amount of a claim item can only be changed by recording a payment transaction which then results in an item payment internally.
Typically the creation of payment transactions happens via the collectAI Landing Page or the collectAI Payments API (to record manual bank transfer from a customer).
All the fields mentioned above are already available today even if the item payments feature is disabled. Enabling item payments however, will result in a more restrictive API behavior (read on)
Claim mutations
First of all, the claim creation (handover) experience stays the same and will work seamlessly. However, as soon as a claim reaches a final state
CONFIRMEDOUT_OF_REACHDISPUTE_RESOLVED
further claim top level modification, like updating a customer name or contact details will not be possible anymore and result in a ConflictError. This will
make your business integration more predictable and robust, since a full dimension of update side effects will be avoided.
Claim item mutations
The item mutations are more tricky to manage since in this case we deal with money related data flows. In principle, item payments come into play as soon as as a payment transaction gets recorded. Under the hood, the system will generate individual item payment records and attach them to their item counterparts. Once an item has been paid, it will not be possible anymore to change or to delete it. In case you do that, the API will respond with a ConflictError. It is safe to rely on the amount and outstanding fields on the claim / item level to detect such a situation. Keep in mind, you can still perform item updates on unpaid items.
Full and partial payments
We now support proper full or partial claim item payments. A full claim payment will automatically result in all items to be paid. If a claim got partially paid, it means that some of it's items are still unpaid with an outstanding > 0.
At this stage, we support full item payments, partial item payments are possible in the future and the system is prepared for this. Our payment flows reflect this behavior seamlessly. If you need to model internal payment flows, which need to be synced with a claim we provide you APIs to manage this. Please checkout the spec here.
Payment invalidations
In case a wrong payment transaction has been recorded, it is possible to invalidate the transaction. Once a transaction has been invalidated, it is also possible again to modify unpaid items which have been sealed before see. Keep in mind, there can be multiple payment transactions for one claim if you work with partial item payments. The payment invalidation API can be found here.
Claim lifecycle implications
With the new item payments feature, the claim CONFIRMED state will be managed automatically for you. Whenever a claim reaches a outstanding = 0, it will automatically transition to CONFIRMED state. This is also true on the item level if a sequence of partial item payments result in a full payment.