Financial Flow

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

What is Invoicing?

Invoicing is the process of documenting and issuing formal requests for payment from a business to its customers. In the context of an insurance platform, invoicing plays a critical role in:

• Tracking financial transactions related to policyholders.
• Collecting payments for various policy-related services.
• Ensuring timely and transparent communication regarding due amounts.

It involves the generation of detailed billing records (invoices), tracking of installment schedules, payment processing, and allocation of funds against policies.

The following endpoints describe the API process of payments and invoice allocation in the application.

Endpoint - Insert payment

Summary

This API endpoint is used to insert a payment made by a customer or broker into the ledger. It records essential payment details including amount, date, currency, payer type, and optional descriptions. It's typically the first step in the payment processing workflow, followed by payment allocation to an invoice.

curl -i -X POST \
  https://ledger.app.beta.insly.training/api/v1/ledger/brokerpayments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{
    "data": {
      "broker": {
        "shortName": "string"
      },
      "paymentSum": 0,
      "description": "string",
      "paymentDate": "2019-08-24",
      "paymentType": "string",
      "paymentCurrency": "string"
    }
  }'

{
  "data": [
    { … }
  ]
}

What Is the Result of the API Call?

If the request is successful, the API responds with a structured confirmation of the recorded payment, including:

• Payment amount, date, currency
• Customer ID and payer type
• A schema reference confirming the ledger record type ("type": "payment", "name": "default")

This response confirms that the payment was successfully registered in the system but does not allocate it to any invoice — that must be done in a separate step via allocate invoice call.

Notes

This endpoint only records a payment. It does not allocate the payment to an invoice — a separate call to the allocation endpoint is required.

payerType must be either "customer" or "broker".

paymentDate must follow the YYYY-MM-DD format.

In order to insert payment, the user must know the customerId or broker.shortName parameter - both are available in policy data and can be fetched using the /ledger/policies/{policyId}/links endpoint and need to be used based on payerType value.

Endpoint - Allocate invoice

Summary

This endpoint is used to apply (allocate) a previously inserted payment (created via /brokerpayments) to a specific policy invoice. It finalizes the payment flow by linking the payment sum to the correct invoice number based on the policy and payment details.

curl -i -X POST \
  https://ledger.app.beta.insly.training/api/v1/ledger/brokerpayments/allocate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

{
  "requestId": "8bb0e40f-6841-47fc-a283-b6a43c6e299e"
}

What Is the Result of the API Call?

If successful, the system returns a requestId, confirming that the allocation operation has been submitted and accepted.

This step does not return full invoice or policy details, but it confirms the payment has been assigned to the invoice, which can then be queried elsewhere for updated status.

Notes

A correct match of paymentSum and invoiceNo is essential — under- or over-allocation might cause an error or partial allocation behavior depending on system settings.

This call is idempotent — repeated requests with the same data won't cause duplicate allocations.

Endpoint - Credit invoice

Purpose

The credit invoice process is used to mark invoice as unpaid after it has been marked as paid (credit the affected invoice). As a result of this action the payment sum will move back to the client's or broker's prepayment account and can be allocated to the correct invoice.

curl -i -X POST \
  'https://ledger.app.beta.insly.training/api/v1/ledger/broker-payments/{eventId}/credit' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

Notes

Invoice total, amount to pay, and payment sum must be set to 0.00.

The system will require a valid source invoice ID that the credit note refers to.

Any malformed or missing data will cause the invoice crediting to fail.