POSTing checks

Check creation in ClaimCenter

Checks and validation levels

Both claims and exposures have validation levels. A validation level is a designation of how mature the claim or the exposure is. Every validation level can have a set of validation criteria tied to it. A claim or an exposure cannot reach a given validation level until all the associated validation criteria have been met.

In most instances of ClaimCenter, the highest validation level is "Ability to pay". This means that the claim or exposure is at the point where checks can be written.

In order to create a check set, the following must be true:

  • The claim's validation must be "Ability to pay".
  • Each exposure that owns a reserve line that payment transactions are coming from must also be at "Ability to pay".

For more information on validating claims, see Validating claims. For more information on validating exposure, see Validating exposures.

Checks and payment types

When a check is created, each underlying payment can have one of three types:

  • Final - This applies to open claims and exposures. This indicates that no additional payments are expected to be made from the corresponding reserve line.
  • Partial - This applies to open claims and exposures. This indicates that additional payments may be made from the corresponding reserve line.
  • Supplement - This is used to make payments on closed claims and exposures.

Check creation through Cloud API

When creating checks from Cloud API, there is no POST endpoint whose root resource is a check or a payment transaction. Checks and payment transactions are created within the context of a check set. Keep in mind that check sets can be created only for claims at or above "Ability to pay" and using only exposures at or above "Ability to pay".

To create a check set, use the following endpoint:

  • POST /claims/{claimId}/check-sets

Prior to creating the check set, you will need the following:

  • For each reserve line the checks will be drawing from:
    • The ID of the parent exposure. (If the reserve line is at the claim level, then specify "null" for the exposure ID.)
    • The reserve line's cost type, cost category, and currency.
  • For each payee that is already on the claim:
    • The ID of the corresponding contact.

The primaryCheckToWrite object

When you create a reserve set, you must specify the primaryCheckToWrite . At a minimum, it must consists of the following three items.

You must specify an array of paymentsToWrite. For each member of the array, you must specify:

  • An array of one or more transaction lineItems, each of which must specify:
    • A transactionAmount (specified as an amount and a currency)
  • A paymentType (a value from the PaymentType typelist, such as partial or final)
  • The reserveLine that the money is coming from. To identify this, you must specify:
    • costCategory (a value from the CostCategory typelist)
    • costType (a value from the CostType typelist)
    • The id of the parent exposure
    • The reservingCurrency
  • The payment transaction currency

You must also specify an array of payees. For each payee you must specify:

  • An ID for the payee
    • If the contact already exists on the claim, you can reference it by its id.
    • If the contact does not exist on the claim, you can create it in the same call using request inclusion and reference it using a refid.
  • The payeeType (a value from the ContactRole typelist filtered by payee, such as insured, claimant, vendor, or other)

You must also specify the paymentMethod. This is a value from the PaymentMethod typelist, such as check or eft.

Currencies in the POST check-sets payload

Every payment transaction consists of one of more line items. Payment transactions and line items are stored in different database tables. However, for a given payment transaction, the currency of every line item in the payment transaction must match the currency of the payment transaction.

This distinction may not be evident when using the user interface. The user chooses a currency for a check set, and all line items automatically default to that currency. This hides the fact that they are technically distinct values.

However, this distinction must be taken into consideration when writing a check set payload. There is no mechanism for the line items to inherit the payment transaction's currency. Therefore, the currency of the payment transaction and each line item must be explicitly stated, and they must be the same.

There is a third field that is set to a currency value, reservingCurrency. This must always be specified. In an instance of ClaimCenter that makes use of multicurrency, this can be set to a currency other than the reserve transaction's currency. For more information, see Multicurrency.

Checks and composite requests

Within a composite request, you cannot create or modify financial objects. This includes check sets and payment transactions. However, within a composite request, you can GET information on financial objects.

Example of creating a minimal check set

The following payload is an example of creating a check set.

  • The ID of the claim is cc:55. This claim is at "Ability to pay".
  • The money will come from a single exposure, which is also at "Ability to pay".
    • The exposure's ID is cc:58.
    • The cost type is claimcost.
    • The cost category is Auto Body (body).
  • There is only one payment transaction.
    • The currency and reserving currency is USD.
    • The amount is $75.50.
    • The payment is final.
  • There is only one payee.
    • The payee's contact ID is cc:613.
    • The payee's type is insured.
  • The payment method is Electronic Funds Transfer (eft).
POST /claims/cc:55/check-sets

{
  "data": {
    "attributes": {
      "primaryCheckToWrite": {
        "paymentsToWrite": [
          {
            "lineItems": [
              {
                "transactionAmount": {
                  "amount": "75.50",
                  "currency": "usd"
                }
              }
            ],
            "paymentType": {
              "code": "final"
            },
            "reserveLine": {
              "costCategory": {
                "code": "body"
              },
              "costType": {
                "code": "claimcost"
              },
              "exposure": {
                  "id": "cc:58"
              },
              "reservingCurrency": {
                "code": "usd"
              }
            },
            "currency": {
              "code": "usd"
            }
          }
        ],
        "payees": [
          {
            "contact": {
              "id": "cc:613"
            },
            "payeeType": {
              "code": "insured"
            }
          }
        ],
        "paymentMethod": {
          "code": "eft"
        }
      }
    }
  }
}