Factoring Integration

This guide describes how factoring can be activated for a company through the Unimicro API, how invoices are marked as waiting for factoring, and how a factoring partner can accept or decline invoices.

Factoring is configured through FactoringSettings. The activation payload follows the structure of ActivateFactoringDto. Invoices are handled through the CustomerInvoice model.

How factoring works

The factoring flow consists of four main steps:

1. Factoring is activated for the company.
2. The factoring setup is stored as FactoringSettings.
3. When an invoice is sent with factoring, the invoice is put on hold with status 42503 — Waiting for factoring.
4. The factoring partner accepts or declines the invoice through an invoice action.

When the invoice is accepted, Unimicro sends the invoice and handles accounting according to the factoring setup.

Prerequisites

Before activating factoring, the following must exist on the company:

• A bank account used for payment/KID.
• An account or subledger account for the factoring company.
• A loan or interim account for the factoring flow.
• A valid KID/payment setup using PaymentInfoType.

The activation payload uses account numbers, not internal account IDs.

Typical fields:

Activate factoring

Factoring is activated by calling the activate-factoring action on FactoringSettings.

The request body follows the structure of ActivateFactoringDto.

Example request

{
  "BankAccountNumber": "62631284979",
  "FactoringAccountNumber": 1501,
  "FactoringCustomerNumber": "8055",
  "FactoringDistribution": 1,
  "FactoringLoanAccountNumber": 2381,
  "FactoringPaymentInfo": {
    "Length": 18,
    "Modulus": 10,
    "HasKid": true,
    "Name": "test factoring",
    "PaymentInfoTypeParts": [
      {
        "Part": "kid_prefix",
        "Length": 1,
        "SortIndex": 1
      },
      {
        "Part": "customer_number",
        "Length": 4,
        "SortIndex": 2
      },
      {
        "Part": "invoice_number",
        "Length": 8,
        "SortIndex": 3
      },
      {
        "Part": "kid_code",
        "Length": 2,
        "SortIndex": 4
      },
      {
        "Part": "check_digit",
        "Length": 1,
        "SortIndex": 5
      }
    ],
    "StatusCode": 42400,
    "Type": 1
  },
  "NotificationsText": "The invoice has been transferred to a factoring company. Payment must be made to the specified account/KID.",
  "SkipJournalEntry": false
}

A successful activation returns the created factoring setup. Factoring will then be available as a sending option for invoices.

Activation payload

FactoringDistribution

Use 1 when the invoice should be distributed from the Unimicro/Softrig flow.

KID and PaymentInfoType

FactoringPaymentInfo describes how the KID is built.

The example above uses these KID parts:

Rules:

• Length must match the total KID length.
• PaymentInfoTypeParts are sorted by SortIndex.
• Numeric parts are left-padded according to the defined length.
• Use Modulus: 10 for modulus 10.
• Do not use the string value "modulus10".
• Set HasKid to true when KID should be used.

Retrieve factoring settings

The factoring setup can be retrieved from FactoringSettings.

Example with expanded relations:

Relevant fields include:

Note: GET /factoringsettings may return previously created factoring settings. The response does not necessarily indicate clearly which setup is currently active.

Deactivate factoring

Factoring can be deactivated with the deactivate-factoring action.

A successful deactivation normally returns:

Deactivation removes factoring as an available sending option. Existing FactoringSettings may still be returned from GET /factoringsettings.

Invoices waiting for factoring

When an invoice is sent with factoring, the invoice is put on hold while waiting for the factoring partner.

The partner can retrieve invoices waiting for factoring by filtering invoices on status code.

Example with selected fields:

For more information about filtering, see

Query API-requests.

Accept or decline an invoice

When an invoice is waiting for factoring, the factoring partner must accept or decline it.

Accept invoice

Fields:

Example:

{
  "externalStatus": 42601,
  "externalDebtCollectionReference": "CASE-123456",
  "externalDebtCollectionNotes": "Accepted for financing"
}

When accepted, the invoice is sent and Unimicro handles accounting according to the factoring setup.

Decline invoice

Fields:

Example:

{
  "reason": "Credit limit exceeded"
}

When declined, a reason can be added explaining why the invoice was not accepted.

External invoice status

The factoring partner can set an external status on the invoice.

ExternalStatusCodeCustomerInvoice:

This is the partner’s external status and should not be confused with CustomerInvoice.StatusCode.

Accounting effect when accepted

When the partner accepts the invoice:

• Unimicro uses the setup stored in FactoringSettings.
• The invoice is posted according to the factoring setup.
• The factoring company is handled through the configured account/subledger and loan/interim account flow.
• Settlement is normally handled against the loan/interim account.

The exact accounting effect depends on the company’s chart of accounts and factoring setup.

Polling and webhooks

A partner can retrieve invoices waiting for factoring by polling:

Alternatively, the partner can be configured with webhook/Eventplan for invoice-related events. For general webhook setup, see

Configuring Webhooks with Eventplans.

When using webhooks, the filter should be limited to the invoice statuses/events relevant to the factoring flow. Confirm the concrete webhook filter for each integration.

Common error sources

Account does not exist

Activation fails if the bank account or account numbers in the payload do not exist on the company.

Check especially:

• BankAccountNumber
• FactoringAccountNumber
• FactoringLoanAccountNumber

Error message may point to an unclear account reference

When an account is missing, the error message may be unclear. Check both the factoring account and the loan/interim account if activation fails on account lookup.

Incorrect KID setup

Check that:

• Length matches the expected KID length.
• PaymentInfoTypeParts have the correct Length.
• SortIndex is in the correct order.
• Modulus is set to 10 for modulus 10.
• HasKid is true.
• KID parts are left-padded correctly.

Deactivation is not clearly visible in the API response

After deactivation, GET /factoringsettings may still return the setup. This does not necessarily mean that factoring is active. Check whether factoring is available as a sending option.

Complete example

Activate factoring

{
  "BankAccountNumber": "62631284979",
  "FactoringAccountNumber": 1501,
  "FactoringCustomerNumber": "8055",
  "FactoringDistribution": 1,
  "FactoringLoanAccountNumber": 2381,
  "FactoringPaymentInfo": {
    "Length": 18,
    "Modulus": 10,
    "HasKid": true,
    "Name": "test factoring",
    "PaymentInfoTypeParts": [
      {
        "Part": "kid_prefix",
        "Length": 1,
        "SortIndex": 1
      },
      {
        "Part": "customer_number",
        "Length": 4,
        "SortIndex": 2
      },
      {
        "Part": "invoice_number",
        "Length": 8,
        "SortIndex": 3
      },
      {
        "Part": "kid_code",
        "Length": 2,
        "SortIndex": 4
      },
      {
        "Part": "check_digit",
        "Length": 1,
        "SortIndex": 5
      }
    ],
    "StatusCode": 42400,
    "Type": 1
  },
  "NotificationsText": "The invoice has been transferred to a factoring company. Payment must be made to the specified account/KID.",
  "SkipJournalEntry": false
}

Retrieve factoring settings

Find invoices waiting for factoring

Accept invoice

{
  "externalStatus": 42601,
  "externalDebtCollectionReference": "CASE-123456",
  "externalDebtCollectionNotes": "Accepted for financing"
}

Decline invoice

{
  "reason": "Credit limit exceeded"
}

Deactivate factoring

Expected response:

Partner onboarding checklist

• Bank account exists on the company.
• Factoring account exists in the chart of accounts.
• Loan/interim account exists in the chart of accounts.
• FactoringCustomerNumber is clarified with the factoring company.
• FactoringDistribution is set correctly.
• FactoringPaymentInfo is configured with the correct KID format.
• Factoring is activated with PUT /factoringsettings?action=activate-factoring.
• Factoring appears as an available sending option.
• Partner can retrieve invoices with StatusCode = 42503.
• Partner can accept invoices with factoring-accepted.
• Partner can decline invoices with factoring-declined.
• Polling or webhook/Eventplan setup is clarified.