Account Prolongation

The platform can prolong outstanding invoices (postpone the due date) using the Account Prolongation feature.

Diagram

Account Prolongation 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": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
                "invoiceDetails": {
                    "amount": 100000,
                    "dueDate": "2021-09-08"
                },
                "context": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_3",
                "invoiceDetails": {
                    "amount": 200000,
                    "dueDate": "2021-10-08"
                },
                "context": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            }
        ]
    }
}

for additional information, visit the account overview page

2 Request Prolongation

In order to request a prolongation for the outstanding invoices you can do it with the Backoffice and from the Client API

The side effects of requesting the prolongation are:

  • Present the Prolongation fee in the Backoffice
  • Present the Prolongation fee in the Landing Page

Note.- If the prolongation fee is not paid in one day, the prolongation request is discarded

2,1 Backoffice

Here is an example of an Account with 1 outstanding invoice

Account with Invoices

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

Account Prolongation Account Action Account Prolongation Configuration

And this is how this account looks after applying the prolongation is requested

Account Prolongation With Request

2,2 Client API

Below is a sample request body for requesting account prolongation using the Client API

POST v1/${clientI}/prolong_account_outstanding_invoices?accountReference= HTTP/1.1
Content-Type: application/json
{
	"ACCOUNT_REFERENCE_0001": {
		"days": 21,
		"context": {
			"productReference": "PRODUCT_REFERENCE"
		}
	}
}

Note: Days is the only required field for the request, a more robust description of the endpoint can be found on the API Documentation.

2,3 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOutstandingInvoicesProlongation.requested.v1",
      "receeveClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "prolongationClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "LARS_INVOICE_LEDGER_ENTRY_REFERENCE_100013_3",
          "context": {
            "productReference": "LARS_PRODUCT_REFERENCE"
          },
          "invoiceDetails": {
            "createdAt": 1632309374490,
            "amount": 200000,
            "dueDate": "2021-10-08"
          }
        }
      ],
      "days": 7
    },
    "messageId": "09758ba9-6591-4a82-9b22-fe88062de996",
    "timestamp": "2021-09-22T11:16:59.336Z"
  }
}

3 Account Prolongation Resolved

This happens once the prolongation fee is resolved (paid by the Debtor, paid in the Backoffice using the charge mandate functionality, etc.). Please add any additional adjustment/payments/fees after the webhook is received.

The side effects of resolving the prolongation request are:

  • Remove the Prolongation fee in the Backoffice
  • Remove the Prolongation fee in the Landing Page
  • Discard any other prolongation requests (to avoid side-effect)
  • Add the Adjustment Ledger Entries to the outstanding Invoices Ledger Entries (to change the due date as requested)

3,1 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOutstandingInvoicesProlongation.resolved.v1",
      "receeveClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "prolongationClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "LARS_INVOICE_LEDGER_ENTRY_REFERENCE_100013_3",
          "context": {
            "productReference": "LARS_PRODUCT_REFERENCE"
          },
          "invoiceDetails": {
            "createdAt": 1632309374490,
            "amount": 200000,
            "dueDate": "2021-10-08"
          }
        }
      ],
      "days": 7
    },
    "messageId": "e360b6a3-b10b-4619-b455-0ab40cce71fd",
    "timestamp": "2021-09-22T11:17:31.609Z"
  }
}

3,2 Resolving through the Client API

There are three possible requests to the Client API resulting in the account prolongation being resolved and the fee discarded. All of them use the same endpoint but different request bodies.

3,2,1 Providing the account without any extra information

POST /v1/${clientId}/resolve_prolong_account_outstanding_invoices HTTP/1.1

{
  "ACCOUNT_REFERENCE" : {}
}

3,2,2 Updating the due dates of the invoices

POST /v1/${clientId}/resolve_prolong_account_outstanding_invoices HTTP/1.1

{
  "ACCOUNT_REFERENCE" : {
    "INVOICE_LEDGER_ENTRY_REFERENCE": "2021-10-17"
  }
}

3,2,3 Specifing the prolongation claim reference to resolve

POST /v1/${clientId}/resolve_prolong_account_outstanding_invoices HTTP/1.1

{
  "ACCOUNT_REFERENCE" : {
    "prolongationClaimRef": "PROLONGARTION_CLAIM_REFERENCE"
  }
}

4 Account Prolongation Discarded

The prolongation request is discarded:

  • if the debtor didn't pay the prolongation fee (valid for one day)
  • if the account has any new Ledger Entry into the system (to avoid side-effect)
  • if the client requested to discard the prolongation request using the Backoffice
  • if a prolongation request is resolved it would discard any other prolongation requests (to avoid side-effect)

The side effects of discarding the prolongation request are:

  • Remove the Prolongation fee in the Backoffice
  • Remove the Prolongation fee in the Landing Page

4,1 Backoffice

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

Account Prolong Discard Action Account Prolong Discard Wizard

4,2 Client API

Below is a sample request for discarding account prolongation. You need to provide the prolongation claim reference to discard it.

POST v1/${clientI}/discard_prolong_account_outstanding_invoices HTTP/1.1
Content-Type: application/json
{
  "ACCOUNT_REFERENCE": {
    "prolongationClaimReferences": ["prolongationClaimRef1"]
  }
}

4,3 Webhooks

{
  "payload": {
    "details": {
      "messageType": "event.accountOutstandingInvoicesProlongation.discarded.v1",
      "receeveClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "prolongationClaimRef": "4351c7cf-0d4b-44af-bf06-7cd45404748b",
      "ledgerEntries": [
        {
          "ledgerEntryReference": "LARS_INVOICE_LEDGER_ENTRY_REFERENCE_100013_3",
          "context": {
            "productReference": "LARS_PRODUCT_REFERENCE"
          },
          "invoiceDetails": {
            "createdAt": 1632309374490,
            "amount": 200000,
            "dueDate": "2021-10-08"
          }
        }
      ],
      "days": 7
    },
    "messageId": "e360b6a3-b10b-4619-b455-0ab40cce71fd",
    "timestamp": "2021-09-22T11:17:31.609Z"
  }
}

5,1 Get Account Prolongation

In order to get an account prolongations you can use the ClientAPI. Below is a sample request. You need to provide the account reference to return all the account prolongations.

GET v1/${clientI}/get_account_prolongation_requests?accountReference=ACCOUNT_REFERENCE HTTP/1.1
Content-Type: application/json

Notes

  • The prolongation Fee is client specific, at the moment is not configurable in the backoffice
  • The prolongationClaimRef represents the prolongation process and is unique per prolongation request
  • We can have more than one active Prolongation Requests per Account but if any of them is resolved it would discard the others
  • 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