Debtor Collection

Introduction

If an invoice is overdue, Credit Management is activated and its scheme will run with its defined steps and actions. If a debtor has multiple overdue invoices, multiple schemes are carried out for the debtor. This can cause an overload of communication, making it harder for the debtor to keep track of which invoices are overdue and their individual payment terms. Additionally, it can become cumbersome to fulfill the invoices, as each invoice must be paid individually through its own pay links. The goal of Credit Management is to perform the right actions to motivate the debtor to fulfill their payment obligation. Multiple overdue invoices can complicate this process.

Debtor Collection is a feature that simplifies the credit management process if a debtor has multiple overdue invoices. Instead of running a scheme for each individual invoice, all overdue invoices are aggregated into a "Debtor File." The Debtor File then runs its own scheme on behalf of all invoices in it. Actions and communication performed from the Debtor File’s scheme are aimed at getting the Debtor File paid as a whole, as quickly as possible. Its communication should address and specify all overdue invoices clearly and lay out one set of payment terms that apply to all of them at the same time. Additionally, a possibility should be provided to fulfill the overdue invoices with one single payment.

There is no specific pre-configured Debtor File scheme. Instead, a Debtor File will always follow the scheme of the longest overdue invoice in the Debtor File. This invoice is called the "leading invoice." The Debtor File carries out the steps and actions of the leading invoice’s scheme, but these actions will have a slightly different execution in the context of a Debtor File.

Flow

  • Single Overdue Invoice:

    • If a debtor has only one overdue invoice, its scheme will run its actions and these are performed for standard Credit Management.
  • Multiple Overdue Invoices:

    • If a second invoice of the debtor becomes overdue, its scheme will not be carried out. Instead, a Debtor File is created, and both the first and second invoices are added to the Debtor File.
    • The first invoice will be identified as the leading invoice, as it has the oldest due date.
    • The Debtor File will then follow the scheme of the leading invoice and resume the scheme where it left off, since it already made progression. From then on, every action in the scheme is performed on the Debtor Collection level.
    • As long as the Debtor File is active, any subsequent invoice of this debtor that becomes overdue will be added to the Debtor File.
    • If a Debtor File remains unpaid and reaches the end of its scheme, the final actions are executed, and the Debtor File is terminated. The invoices in the Debtor File will not resume their individual schemes, ending Credit Management for all invoices.
    • A debtor can only have one active Debtor File at a time. Once a Debtor File is terminated (by fulfillment or ending its scheme), a new one will be created once a second invoice becomes overdue.
  • Separate Payments:

    • Invoices in a Debtor File can still be paid separately. If an invoice in a Debtor File is fully paid, it will be removed from the Debtor File. The Debtor File continues its Credit Management process for the remaining open invoices.
    • If the paid invoice was the leading invoice, the Debtor File will follow the scheme of the next oldest invoice, extending the time for the debtor to fulfill the Debtor File.

Payments and Refunds

  • Single Payment:

    • A Debtor File has its own pay link for performing a single transaction to fulfill every invoice in the Debtor File. Buckaroo will register an external payment transaction for each invoice in the Debtor File.
    • Alternatively, fulfillment can be done via bank transfer using the Debtor File number as a reference.
  • Partial Payments:

    • If a lower amount than needed is transferred, Buckaroo will fulfill the oldest overdue invoice to the newest one until all invoices are paid. The Debtor File remains active if there are still outstanding amounts.
  • Separate Payments:

    • Invoices can be paid individually using their pay link or bank transfer. The Debtor File data is updated accordingly.
  • Refunds:

    • If a debtor file payment is (partially) refunded, the merchant decides which invoices to reopen by refunding related external payments. The refund of an external payment is informational.

Configuration

  • Enabling Debtor Collection:

    • For an invoice to be included in a Debtor File, its scheme must have Debtor Collection enabled. This option can be turned on in the scheme.
  • Alternative Messages:

    • Set up alternative Debtor Collection messages for reminders and custom events.
  • Reminders:

    • For reminders, set an alternative Debtor Collection message next to the Standard Credit Management message. A default template is available for setting up the Debtor Collection reminder in the scheme.
  • Custom Events:

    • For custom events, set an alternative Debtor Collection custom event.
  • Admin Fee:

    • Only charged for the leading invoice and therefore only once per Debtor File, as charging multiple admin fees is not legally permitted.
  • Transfer to Collection Agency:

    • All invoices in a Debtor File are transferred to the collection agency.
  • Stop Subscription:

    • All Buckaroo subscriptions linked to invoices in a Debtor File will be stopped.
  • Threshold:

    • A Debtor File will ignore thresholds, as Debtor Collection aims to stimulate the debtor to fulfill multiple overdue invoices.

Push

A Debtor File follows the scheme of the leading invoice. Therefore, every scheme event will only be pushed from the leading invoice. Events like financial mutations are always pushed for the involved invoices. In any case, an invoice that is part of a Debtor File will always specify the DebtorFileGuid, DebtorFileNumber and the DebtorFilePayLink.


Parameters

ParameterTypeRequiredRecommendedDescription
DebtorFileGuidstringUnique identifier of the Debtor File
DebtorFileNumberstringBank Transfer reference for the consumer to include in the Transfer's description. By providing the DebtorFileNumber, the transferred amount will be used fulfill the invoices in the Debtor File.
DebtorFilePaylinkstringPaylink to fulfill the Debtor File

Example Push

{
  "Invoice": {
    "InvoiceKey": "E3409F142BD94BB3B8047A73",
    "InvoiceNumber": "INV0001",
    "WebsiteKey": "vcKCNXSCDw",
    "DebtorCode": "JohnSmith123",
    "DebtorGuid": "903FADD72ABC4A6E91FCA5AE4",
    "SchemeKey": "abc123",
    "IsTest": false,
    "Type": "RegularInvoice",
    "Culture": "nl-NL",
    "InvoiceDate": "2021-10-01T00:00:00",
    "DueDate": "2021-10-01T00:00:00",
    "InvoiceStatusCode": 10,
    "PreviousStepIndex": 1,
    "PreviousStepDateTime": "2021-11-18T14:04:03",
    "InvoicePayLink": http://checkout.local/html/?brq_paydirect_inv=XXX,
    "Event": "SentReminderMessage",
    "EventCategory": "Other",
    "EventDateTime": "2021-11-18T14:06:29.7783014",
    "EventParameters": [
      {
        "Key": "CommunicationMethod",
        "Value": "Email"      },
      {
        "Key": "Template",
        "Value": "_Buckaroo.DebtorCollectionReminder.en.html"      }
    ],
    "Currency": "EUR",
    "AmountDebit": 0.0500,
    "AmountCredit": 0.0000,
    "AmountAdminCosts": 0.0000,
    "AmountCreditNotes": 0.0,
    "AmountPaid": 0.0,
    "AmountAdminCostsPaid": 0.0,
    "AmountPendingSlow": 0.0,
    "OpenAmount": 0.0500,
    "OpenAmountAdminCosts": 0.0000,
    "OpenAmountInclAdminCosts": 0.0500,
    "IsPaid": false,
    "CustomParameters": [
    ],
    "AdditionalParameters": [
    ],
    "DebtorFileGuid": "3B82F6ECDC1D4CF5BC856",
    "DebtorFileNumber": "DNR000000106",
    "DebtorFilePayLink": http://checkout.local/html/?brq_paydirect_debtor_file=123 }
}

ResumeDebtorFile

Resumes a paused Debtor File. A Debtor File will be automatically paused if a reminder could not be sent due to incorrect or missing information.


Request

Parameters

ParameterTypeRequiredRecommendedDescription
DebtorFileGuidstringRequiredUnique identifier of the Debtor File.

Example Request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "CreditManagement3",
        "Action": "ResumeDebtorFile",
        "Parameters": [
          {
            "Name": "DebtorFileGuid",
            "Value": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
          }
        ]
      }
    ]
  }
}

Response

Example Response

{
  "Key": "A6FEBD16BD5849B38CF1AF3DBDB1",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-11-19T15:29:40"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "Creditmanagement3",
  "IsTest": false,
  "ConsumerMessage": null
}

PauseDebtorFile

Perform this action to pause a debtor file


Request

Example Request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "CreditManagement3",
        "Action": "PauseDebtorFile",
        "Parameters": [
          {
            "Name": "DebtorFileGuid",
            "Value": ""
          }
        ]
      }
    ]
  }
}

Response

Example Response

{
  "Key": "D9B6D3B23FE245CA91E459326D0XXXXX",
  "Status": {
    "Code": {
      "Code": 490,
      "Description": "Failed"
    },
    "SubCode": {
      "Code": "S172",
      "Description": "Debtor file with key DAF93790B6CC489691658B814CCCCC is not active."
    },
    "DateTime": "2022-06-13T18:10:00"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "CreditManagement3",
  "IsTest": false,
  "ConsumerMessage": null
}