Account Restructuring

The platform should be able to convert/restructure already missed invoices from an Account into a Instalment Plan. Depending on the outcome of the Instalment Plan, update the Account accordingly.

Diagram

Account Restructure Diagram

1 Create Account

In order to create an account you can use the Client API with a request like this one:

POST /v1/${clientI}/create_accounts HTTP/1.1
Content-Type: application/json

{
    "ACCOUNT_REFERENCE_0001": {
        "currency": "EUR",
        "meta": {},
        "scores": [
            {
                "type": "INTERNAL",
                "value": "V1"
            }
        ],
        "debtors": [
            {
                "lastName": "LAST_NAME",
                "firstName": "FIRST_NAME",
                "debtorReference": "EXTERNAL_DEBTOR_REF_0001",
                "contactInformation": {
                    "country": "DE",
                    "email": "debtor@company.com"
                }
            }
        ],
        "products": [
            {
                "productReference": "PRODUCT_REFERENCE"
            }
        ],
        "ledgerEntries": [
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
                "invoiceDetails": {
                    "amount": 100000,
                    "dueDate": "2021-08-08"
                },
                "context": {}
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
                "invoiceDetails": {
                    "amount": 100000,
                    "dueDate": "2021-09-08"
                },
                "context": {}
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_3",
                "invoiceDetails": {
                    "amount": 200000,
                    "dueDate": "2021-10-08"
                },
                "context": {}
            }
        ]
    }
}

for additional information, visit the account overview page

2 Request Restructuring

In order to request to restructure the account the system offers two options, you can do it the Backoffice or with the Client API

The side effects of requesting the restructuring are:

  • Pause Collection Strategy from Restructured Invoices
  • Present the Restructure process in the Backoffice
  • Present the Restructuring process in the Landing Page

2,1 Backoffice

Here is an example of an Account with 2 overdue invoices

Account with Invoices

In order to request the restructuring you have to follow this wizard:

Account Restructure Account Action Account Restructure Configuration Account Restructure Simulation

And this is how this account looks after applying the restructuring

Account Restructured

2,2 Client Api

The equivalent but through the Client API is a request like this:

POST /v1/${clientId}/restructure_account_overdue_invoices HTTP/1.1
Content-Type: application/json

{
    "ACCOUNT_REFERENCE_0001": {
        "amounts": [50000, 50000, 50000, 50000],
        "frequency": {
            "months": 1
        },
        "initialDueDate": "2021-09-21"
    }
}

2,3 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOverdueInvoicesRestructure.requested.v1",
      "receeveClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "restructureClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074088,
            "amount": 100000,
            "dueDate": "2021-08-08"
          }
        },
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074586,
            "amount": 100000,
            "dueDate": "2021-09-08"
          }
        }
      ],
      "instalmentsPlan": {
        "amounts": [
          50000,
          50000,
          50000,
          50000
        ],
        "frequency": {
          "months": 1
        },
        "initialDueDate": "2021-09-21"
      }
    },
    "messageId": "dcf889d6-61f4-4e41-8ff6-e57ceb4f2d31",
    "timestamp": "2021-09-20T18:40:30.674Z"
  }
}

3 Discard the Account Restructuring

The side effects of discarding the restructuring are:

  • Resume Collection strategy from Restructured non-paid Invoices
  • Remove Restructure process in the Backoffice
  • Remove Restructuring process in the Landing Page

We offer two options to do it, through the Backoffice or with the Client Api

3,1 Backoffice

In order to discard the account restructuring you have to follow this wizard:

Account Restructure Discard Action Account Restructure Discard Wizard

3,2 Client Api

POST /v1/${clientId}/discard_restructure_account_overdue_invoices HTTP/1.1
Content-Type: application/json

[
    { "ref": "ACCOUNT_REFERENCE_0001" }
]

3,3 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOverdueInvoicesRestructure.discarded.v1",
      "receeveClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "restructureClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074088,
            "amount": 100000,
            "dueDate": "2021-08-08"
          }
        },
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074586,
            "amount": 100000,
            "dueDate": "2021-09-08"
          }
        }
      ]
    },
    "messageId": "bed83b84-d7f5-4b4e-9afe-5d5e0246a27d",
    "timestamp": "2021-09-20T19:22:14.220Z"
  }
}

4 Account Restructuring Failed

This happens once the debtor failed to pay any of the instalments of the restructuring process. Make sure to apply any adjustments/fees/payments before discarding the restructure process.

4,1 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOverdueInvoicesRestructure.failed.v1",
      "receeveClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "restructureClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074088,
            "amount": 100000,
            "dueDate": "2021-08-08"
          }
        },
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074586,
            "amount": 100000,
            "dueDate": "2021-09-08"
          }
        }
      ]
    },
    "messageId": "bed83b84-d7f5-4b4e-9afe-5d5e0246a27d",
    "timestamp": "2021-09-20T19:22:14.220Z"
  }
}

5 Resolve the Account Restructuring

This triggers the same result as if the debtor paid successfully all the instalments from the restructuring flow, is meant to be used if the payments happened offline. Make sure to apply all payments after resolving the restructure process.

5,1 Client Api

POST /v1/${clientId}/resolve_restructure_account_overdue_invoices HTTP/1.1
Content-Type: application/json

[
    { "ref": "ACCOUNT_REFERENCE_0001" }
]

5.2 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOverdueInvoicesRestructure.resolved.v1",
      "receeveClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "restructureClaimRef": "b897222b-39fa-4edb-9d62-0a96702c0faa",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074088,
            "amount": 100000,
            "dueDate": "2021-08-08"
          }
        },
        {
          "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
          "context": {},
          "invoiceDetails": {
            "createdAt": 1632163074586,
            "amount": 100000,
            "dueDate": "2021-09-08"
          }
        }
      ]
    },
    "messageId": "17cab0e2-27c8-49d9-9498-01e01efb6e38",
    "timestamp": "2021-09-20T19:23:42.436Z"
  }
}

Notes

  • Only one restructure can be active at the time per Account
  • The restructureClaimRef represents the restructure process is unique per restructure request
  • Each webhook contains the payloadAsString and signature fields used to validate the sender, but the validation is out of scope of this document.

ON THIS PAGE