Account discount

The platform should be able to request a Discount to some invoices.

Diagram

Account Discount 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 Discount

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

The side effects of requesting the discount are:

  • Present the Discount process in the Backoffice

2.1 Backoffice

Here is an example of an Account with 2 overdue invoices

Account with Invoices

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

Account Discount Select Claim Account Discount Configuration

2.2 Client API

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

POST /v1/${clientId}/request_account_discount?accountReference=CHRISEPM_ACCOUNT_REFERENCE_000006 HTTP/1.1
Content-Type: application/json

{
    "CHRISEPM_ACCOUNT_REFERENCE_000006-CHRISEPM_INVOICE_LEDGER_ENTRY_REFERENCE_000006_1": {
        "context": {
            "discounts": [
                {
                    "discount": 50,
                    "current": 20000,
                    "discountApplied": 10000,
                    "type": "ORDENARY_INTEREST"
                },
                {
                    "discount": 50,
                    "current": 30000,
                    "discountApplied": 15000,
                    "type": "MORATORY_INTEREST"
                },
                {
                    "discount": 50,
                    "current": 100000,
                    "discountApplied": 50000,
                    "type": "PRINCIPAL"
                }
            ]
        }
    }
}

2.3 Webhooks

{
  "payload": {
    "details": {
      "accountReference": "ACCOUNT_ID",
      "messageType": "event.accountDiscount.requested.v1",
      "receeveClaimRef": "EXTERNAL_CLAIM_REF",
      "discountId": "DISCOUNT_ID",
      "discounts": [
        {
          "type": "MORATORY_INTEREST",
          "ledgerEntryReference": "LEDGER_REFERENCE",
          "fullAmount": 100000,
          "amount": 50000,
          "percentage": 50
        }
      ]
    },
    "messageId": "9b72ff0b-bfd4-4be1-8e22-d21731af064e",
    "timestamp": "2020-02-12T10:59:00.272Z"
  }
}

3 Discount Request Approved

3.1 Apply Discount

If you fully manage the account ledger, to apply a discount we have two ways to do it.

  1. Adding discount Ledger Entries with the amount to reduce in the discount.

OR

  1. Updating adjustment Ledger Entries Amount with the reason DISCOUNT, with the absolute amount that you want to have for the invoice or fee being discounted.

If you don't manage the account ledger, you can trigger the resolve endpoint in the ClientAPi. This will apply each discount requested in the context of the discount request and create the needed ledger entries (see Section 2).

3.1.1 Adding the Discount Ledger Entries

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

[
  {
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "DISCOUNT_LEDGER_ENTRY_REFERENCE",
    "type": "discount",
    "discountDetails": {
        "amount": 500,
    },
    "context": {
        "ledgerEntryReference": "TARGET_INVOICE_OR_FEE_LEDGER_ENTRY_REFERENCE"
    }
  }
]

3.1.2 Updating the Adjustment Ledger Entries Amount

Using the following endpoint with the reduced amount

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

[
  {
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntries": [
      {
        "ledgerEntryReference": "TARGET_INVOICE_OR_FEE_LEDGER_ENTRY_REFERENCE",
        "amount": 500,
        "reason": "DISCOUNT",
        "meta": {}
      }
    ]
  }
]

3.1.3 Client API

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

{
  "accountReference": {
    "discountClaimRef" : "discountClaimRef1"
  }
}

3.1.4 Webhooks

{
  "payload": {
     "details": {
      "accountReference": "ACCOUNT_ID",
      "messageType": "event.accountDiscount.resolved.v1",
      "receeveClaimRef": "EXTERNAL_CLAIM_REF",
      "discountClaimRef": "EXTERNAL_CLAIM_REF",
      "discounts": [
        {
          "type": "MORATORY_INTEREST",
          "ledgerEntryReference": "LEDGER_REFERENCE",
          "fullAmount": 100000,
          "amount": 50000,
          "percentage": 50
        }
      ]
    },
    "messageId": "9b72ff0b-bfd4-4be1-8e22-d21731af064e",
    "timestamp": "2020-02-12T10:59:00.272Z"
  }
}

4 Discount Request Rejected

We offer one option to do it, with the Client API

4.1 Client API

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

{
  "accountReference": {
    "discountIds": ["discountId1"]
  }
}

4.2 Webhooks

{
  "payload": {
    "details": {
      "accountReference": "ACCOUNT_ID",
      "messageType": "event.accountDiscount.discarded.v1",
      "receeveClaimRef": "EXTERNAL_CLAIM_REF",
      "discountClaimRef": "EXTERNAL_CLAIM_REF",
      "discounts": [
        {
          "type": "MORATORY_INTEREST",
          "ledgerEntryReference": "LEDGER_REFERENCE",
          "fullAmount": 100000,
          "amount": 50000,
          "percentage": 50
        }
      ]
    }
    "messageId": "9b72ff0b-bfd4-4be1-8e22-d21731af064e",
    "timestamp": "2020-02-12T10:59:00.272Z"
  }
}

5 Discard Already Applied Discount

Add Adjustment Ledger Entries referencing the discount with the same amount as the discount but negative. Example: if the discount's amount is 42, then create an adjustment of -42 referencing the discount.

5.1 Adding the Adjustment Ledger Entries

Adding the Adjustment Ledger Entries with the positive amount

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

[
  {
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "DISCARD_DISCOUNT_ADJUSTMENT_LEDGER_ENTRY_REFERENCE",
    "adjustmentDetails": {
        "amount": 500
    },
    "context": {
        "ledgerEntryReference": "DISCARD_DISCOUNT_LEDGER_ENTRY_REFERENCE"
    }
  }
]

Notes

  • The DiscountId represents the Discount process and is unique per Discount
  • 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