Working with debt collection endpoints

Intro

Use case description on how to receive and update debt collection cases via the Magicline Open API.

Relevant Endpoints

Receiving and accepting an integration request

Please refer to Managing Activations.

Retrieving Debt Collection Cases

Once a debt collection run is verified by a studio, the FINANCE_DEBT_COLLECTION_RUN_CREATED webhook is triggered (see Event types). This event contains an ID (entityId), referring to the unique debt collection run, containing all cases. However, it won't include the actual debt cases.

Developers are required to fetch information about debtors and debt cases using the following endpoints:

  • GET Get Debtors : Returns debtors for specified debtCollectionRunId in slices
  • GET Get Transfer Details : Provides holistic data about the transfer including current status, date, client information, etc.

Important information:

  • debtorId : A unique identifier for the debtor. Note: The ID is unique per studio and not globally.
  • collectionCaseId : The ID of a debtor in a single transfer. Multiple IDs for the same debtor indicates individual debt collection transfers.
  • debtId : An ID of a single debt of a debtor. Necessary for sending case updates.

Both these endpoints utilize the debtCollectionRunId parameter for reference, which was obtained from the FINANCE_DEBT_COLLECTION_RUN_CREATED webhook event's field entityId.

Confirming Debt Collection Case Retrieval

After case retrieval, partners must confirm this action by leveraging the POST Confirm transfer retrieval endpoint. This will inform the studio about a successful data transfer to the partner.

It is highly recommended to confirm the transfer immediately after having received the debt collection cases.

Updating Debt Collection Cases

The handling of updates on cases is carried out via the POST Update debt collection endpoint. The Open Api Token assigned during registration is required to authenticate.

Important:

  • Updates imply the entirety of a debtor's current state, not the difference from the prior state.
  • collectionCaseIds must include all Magicline case IDs related to the partner's case.
  • Payments cumulate. For instance, receiving two payments, one for €10 and another for €15, equates to a total paid amount of €25, not two separate payments.

Additional parameters which can be used by partners:

  • agencyCollectionCaseId : A partner's case ID used by Magicline for reference.
  • publicCollectionCaseId : An optional public case ID that varies from the agencyCollectionCaseId , used for client communication.

All debts relating to the partner's case should be provided in debts (At least one is required, regardless of changes).

Closing a Debt Collection Case

Case closure necessitates setting a closure type. On applying a POSITIVE, NEGATIVE, or REVERSAL type, the debtor's debt collection status in Magicline is removed, facilitating regular collection processes for future or open debts if the debtor maintains studio membership.

For uncollectible debts due to bankruptcy or special agreements, the partner can optionally employ the WRITE_OFF_REMAINING_DEBTS closure type.

In the case of REJECTION, the debtor stays in the debt collection status and all restrictions persist in Magicline. It is mandatory to provide a valid value for rejectionReason in this case. (see the Open API Documentation for a description of the various reasons: POST Update debt collection endpoint)

If a case has been closed by the partner via closure, partners can still report payments, increasing the paidAmount accordingly for Magicline to create a payment in the member account.

Caution: closing a case is considered final! E.g. if one update contains a closure element with type POSITIVE the case is closed in Magicline. If a subsequent update doesn't contain a closure element anymore, the case isn't reopened in Magicline. The member will not be put back into debt collection, until the studio initiates this. This also applies to the WRITE_OFF_REMAINING_DEBTS parameter: if an update contains a closure without WRITE_OFF_REMAINING_DEBTS parameter, and a subsequent update contains a closure with this parameter it will not be handled, since the case is already closed on Magiclines side!

Contract Termination Between Studio and Partner

There are two distinguishable scenarios:

  • A studio may switch to a new debt collection partner, but the old partner keeps handling the cases it already received. The old partner is still able to send updates via Open API to report payments, case closings, etc. as usual. The only difference is that the old partner doesn’t receive any new cases.
  • Contract termination initiated by the studio or the partner. In this case, the following steps might be taken, utilizing the POST Update debt collection endpoint:
  • If initiated by the studio, partners should close the debt collection cases with type as REJECTION and rejectionReason as WITHDRAWN_BY_STUDIO .
  • If initiated by the partner, case closure should happen using REVERSAL type.

Procedure for Direct Customer Payment to Studio

Presently, automatic forwarding of payments from the studio to the partner is unavailable.

If a customer pays directly to the studio, the studio must inform the partner and avoid booking payments in Magicline. Instead, partners should report the payment via Open API as if the payment was received directly. Money transfer arrangements between the studio and the partner are at their discretion.