Skip to main content

Account Claims

This document serves to introduce some of the entities from the Account Domain, the core domain in the platform. Specifically, it focuses on the Claim, which is the main protagonist of the integration with your system.

Claim

The Claim represents an expected payment from the Debtor. It has 3 possible states:

  • Active: The Claim is active, and the Debtor is expected to pay the amount.
  • Resolved: The Claim has been resolved, either by the Debtor paying the amount of the Claim or being canceled for other reasons.
  • Deleted: The Claim has been deleted from the system.

To create a Claim in the system, the minimum information required is:

  • The Claim’s amount.
  • The Claim’s currency.
  • The Claim’s Primary Debtor.
  • The date that the Claim is or was expected to be paid.

This information allows us to know how much money is expected to be paid and who should pay that amount. All the other information is optional and helps facilitate other features in the platform as well as improve the user experience for the Agents and the Debtor.

For example:

{
  "amount": 2000,
  "totalFees": 50,
  "currency": "EUR",
  "currentDueDate": "2019-02-15",
  "originalDueDate": "2018-09-09",
  "primaryDebtor": {
    "lastName": "Doe",
    "firstName": "John",
    "debtorReference": "JOHN_DOE_ID",
    "contactInformation": {
      "country": "DE",
      "email": "john.doe@acme.com",
      "mobileNumber": "+49123456789"
    }
  }
}

This claim represents a missing payment (the due date was some years ago) of 20 euros, and 50 cents of fees, that should be paid by John Doe. It also includes some basic contact information so the system can contact him and help him pay the specified amount.

Of course, something critical is missing here: how do you identify one Claim in the System over another Claim? Each Claim has a unique identifier, the claimReference, that is assigned by your system when it is created in receeve. This identifier is used to identify the Claim in the system and link the Claim to other entities in the system, like the Debtor, Agent, Payment, etc.

Notes:

  • The originalDueDate is the original due date of the claim in your system. If in the past, this is the day when it went past due.
  • The amount and the fees (or any monetary value) must be expressed in cents. For example, 20 euros must be expressed as 2000 cents.
  • The currentDueDate is the current due date of the claim in your system. Use originalDueDate unless you purchased the debt and need this distinction.
  • The debtorReference is the unique identifier of the debtor. It can be any string, but it must be unique for each debtor.

Debtor​

The Debtor is the person or entity that is expected to pay the Claim. The Debtor is a core entity in the system and is used to group Claims that are related to the same Debtor.

Example of a Debtor:

{
  "birthday": "1980-06-28",
  "gender": "M",
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "Benedict",
  "title": "Doctor",
  "companyName": "Acme Brick Co.",
  "debtorReference": "JOHN_DOE_ID",
  "SSN": "422-69-1234",
  "type": "natural",
  "contactInformation": {
    "country": "DE",
    "city": "Dortmund",
    "mobileNumber": "+49123456789",
    "postalCode": 33129,
    "addressLine1": "Boikweg 24",
    "addressLine2": "c/o Acme",
    "addressLine3": "1st floor",
    "landLine": "+492311234567",
    "state": "Dortmund",
    "email": "john.doe@acme.com"
  }
}

Most of the fields are self-explanatory, but there are some that need more context:

  • debtorReference is the Debtor’s unique identifier. It can be any string, but it must be unique for each Debtor. (Required)
  • country is the Debtor’s country, in the form of a 2-digit country code (ISO 3166-1). This is required for the localization and payment providers. (Required)
  • SSN is the Debtor’s unique identifier in their country. It can be any string, but it must be unique for each Debtor. (Optional)
  • birthday is the Debtor’s birthday and must follow the pattern YYYY-MM-DD. (Optional)
  • mobileNumber is the Debtor’s mobile number. This must follow the international phone number pattern +CCNNNNNNNNN. (Optional)
  • landLine is the Debtor’s landline phone number. This must follow the international phone number pattern +CCNNNNNNNNN. (Optional)
  • type is the type of Debtor, either natural or legal. If natural, the firstName and lastName fields are required. If it is legal, the companyName is required. (Optional, default natural)

Claim Grouping​

The platform offers different Entities to start grouping/enriching the Claims in the system. Claims can be grouped using the following:

  • Claims grouped by Debtor (required, soft grouping)
  • Claims grouped by Account (required, hard grouping)
  • Claims grouped by Product (optional, soft grouping)
  • Claims grouped by Creditor (optional, soft grouping)
  • Claims grouped by Portfolio (optional, soft grouping)

To create the Claims grouped by these entities, you need to create the claims with the next fields:

  • debtorReference is the Debtor’s unique identifier. (Required)
  • accountReference is the Account’s unique identifier. (Optional)
  • productReference is the Product’s unique identifier. (Optional)
  • creditorReference is the Creditor’s unique identifier. (Optional)
  • portfolioReference is the Portfolio’s unique identifier. (Optional)

Notes:

  • The Account can be created independently of the Claim, or it can be created when the Claim is created.
  • It is required to specify a relationship between a Claim and an Account, i.e., a Claim cannot exist without an Account. If an Account is deleted, all the claims associated with that Account are deleted as well.
  • The accountReference is optional. If not provided, the system will create the accountReference using the debtorReference as a seed to generate the accountReference. This is useful if you don't have an Account concept in your system, but we encourage you to provide the accountReference to maintain better control of the grouping process.

Advantages of Adding this Context to Claims​

  • Adding more context/information about the Debtor to Claims enables the following additional functionality for users, among other benefits:
    • Some actions require information from the debtor. For example, to send an SMS to the Debtor, you need their mobile number.
    • Debtor information is typically used to personalize communication with the Debtor.
    • Debtor information can be used to authenticate the Debtor on the Landing Page.
  • Adding the Product context to the Claims enables the following additional functionality for users, among other benefits:
    • Show the Claims in the Backoffice grouped by the Product.
    • Show the context of the Product on the Landing Page so the Debtor can better understand the Claim.
    • Use computed variables in the Strategy to change the behavior of the Collection Strategy for the Claims in that Product.
  • Adding the Portfolio context to the Claims enables the following additional functionality for users, among other benefits:
    • Group the claims in the Reports by Portfolio.
    • Use the Portfolio in the Collection Strategy to change the behavior of the Collection Strategy for the Claims in that Portfolio.
  • Adding the Creditor context to the Claims enables you to use it in the Collection Strategy to change the behavior of the Collection Strategy for the Claims with that Creditor.

With these benefits in mind, we highly recommend adding as much context as possible to the Claims to benefit from the full range of features offered by the platform now and any new features provided in the future.

Metadata​

The Claim can have associated metadata that can be used to store any relevant contextual information related to the Claim.

The metadata is used to store information that is not part of the core of the Claim but is useful to have in the system. For example, the metadata can be used to store the reference to an invoice related to the Claim or the reason why the Claim was created.

This metadata is optional and can be added to the Claim anytime, including at creation or during an update to the Claim.

The metadata is not used explicitly by the platform, but it can be useful in several cases, such as:

  • It can be used in the Collection Strategy to filter the Claims that will be processed.
  • It can be used in the Collection Strategy to define the actions that will be executed for the Claims.
  • Metadata in the templates can be used to personalize communication with the Debtor.
  • Metadata in the templates can also be used to personalize the Debtor’s Landing Page.
  • It can be used to enrich the Webhooks sent back to your system. This allows you to see more information about the Claim.

We highly recommend using the metadata to store any information related to the Claim that may be useful in the future. However, it is important to keep in mind that the metadata is not meant to store large amounts of data such as images or documents. Instead, only small pieces of information should be used in these scenarios.

Other Claim Fields​

  • paymentReference is the reference used in payments done on the Landing Page.
  • fees is the list of fees related to the Claim and used to show them on the Landing Page.

Example

Late Payments per Invoice Example​

Let’s assume that in your system a Debtor can have only one active Account, but it can have multiple products, such as a credit card and a loan. We want to create a Claim exclusively when the Debtor is late in the payment of each product. For this example, we will use a claim of 20 euros and 50 cents of interest for a credit card with reference 1234 and another claim for a loan of 50 euros and 10 euros of interest with reference 5678.

We can create these Claims using the following fields:

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/import_claims HTTP/1.1
Host: api.receeve-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "INVOICE_ABC_1": {
    "amount": 2000,
    "totalFees": 50,
    "currency": "EUR",
    "fees": [
      {
        "name": "Interest",
        "amount": 50
      }
    ],
    "accountReference": "ACCOUNT_REFERENCE_XYZ",
    "productReference": "CREDIT_CARD_REFERENCE_1234",
    "currentDueDate": "2019-02-15",
    "originalDueDate": "2018-09-09",
    "primaryDebtor": {
      "lastName": "Doe",
      "firstName": "John",
      "debtorReference": "JOHN_DOE_ID",
      "contactInformation": {
        "country": "DE",
        "email": "john.doe@acme.com",
        "mobileNumber": "+49123456789"
      }
    },
    "meta": {
      "invoiceReference": "INVOICE_ABC_1"
    }
  },
  "INVOICE_XYZ_1": {
    "amount": 5000,
    "totalFees": 1000,
    "currency": "EUR",
    "fees": [
      {
        "name": "Interest",
        "amount": 1000
      }
    ],
    "accountReference": "ACCOUNT_REFERENCE_XYZ",
    "productReference": "LOAN_REFERENCE_5678",
    "currentDueDate": "2019-02-15",
    "originalDueDate": "2018-09-09",
    "primaryDebtor": {
      "lastName": "Doe",
      "firstName": "John",
      "debtorReference": "JOHN_DOE_ID",
      "contactInformation": {
        "country": "DE",
        "email": "john.doe@acme.com",
        "mobileNumber": "+49123456789"
      }
    },
    "meta": {
      "invoiceReference": "INVOICE_XYZ_1"
    }
  }
}

Notes:

  • Notice that every claim has a different productReference, so the Claims are grouped by Product. However, both Claims are related to the same Account and Debtor.
  • We use the Invoice Reference as the Claim Reference, so we can easily update the claim later without querying the system to get the Claim Reference. This means that you are creating a Claim for each invoice that the Debtor missed the payment. There are different strategies to create Claims, and you can use the one that best fits your business.
  • If you want to avoid repeatedly entering the Primary Debtor information in every Claim, you can create the Account first, and then create the Claims using the accountReference field. This allows you to save time by not having to enter the Debtor information in every Claim.
  • In this example, the Claims are related, but the endpoint is not restricted to creating related Claims in the same request.

Depending on your use cases, you can create Claims that represent different entities in your system. In some cases, a Claim in receeve may represent an Installment, a full product (only one claim per product), a single invoice, etc. This depends on your business and how you want to group the Claims. We can provide support in helping you define the best strategy to get the most value out of the receeve platform. So far, most users prefer the use case described in this example.

FAQ

  • How can I manage/see the claims that I have created through the Backoffice? You can see and manage Accounts, Claims, etc. you have created in the Backoffice Account Page.

Related Pages