4. Invoice

Introduction

This api is used to retrieve information related to the customer's invoices.

PayEx supports HTTP headers for tracking that are used for troubleshooting purposes, implement according to specification

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
lf-api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Routes that occurs in examples of this documentation will use the following identifiers

Implementation Guidelines

To ensure optimal experience for end users, it is essential to follow these usage guidelines:

• Fetch only the invoice list initially: Your initial API call for a customer should retrieve only the invoice list, which provides sufficient information to display an overview of each customer’s invoices, both open and closed invoices.
• Request detailed invoice information only when necessary: Make requests for individual invoice details only when the end user explicitly chooses to view details for a specific invoice. Alternatively, if needed, you may limit the initial requests for a customer to retrieve the invoice list, including requests for details of only the open invoices, which typically amount to only 1-2
• Use hypermedia-driven navigation: The Invoice API is hypermedia-driven, meaning each resource links to relevant sub-resources and operations. Rather than preloading data from multiple levels, design your GUI to allow users to click through and access additional details as needed. This approach mirrors the API’s intended structure and minimizes unnecessary API calls.
• Avoid frequent polling: The API is not designed for regular polling of accounts receivable events (e.g., periodically checking the status of all invoices across all customers to see if any have been paid). Automated status checks, such as hourly polling, are unsupported and will degrade performance

These guidelines apply to both front-end applications, such as web portals, and backend processes using the API. It is crucial to incorporate these requirements into your design to prevent excessive API calls and ensure a high-quality user experience.

Invoice

The invoice resource is located under ledger/invoice/v1/ api. This resource is used to get general information about existing invoices and its current state. Creation of new invoices is done through other resource.

Get specific invoice

Invoice list

The List Resource offers an overview of each invoice on a specified customer with key details like InvoiceNo, status, amount, and due date. While it provides less information than a detailed invoice request, it includes the most important attributes for display purposes. Use this resource to minimize API calls and fetch detailed data only when needed.

Use the querystring parameter "customerNo" to list invoices for a specific customer.

Invoice resource properties

Documents

The documents resources contains basic info of each invoice, reminder, letters etc. that has been produced related to the invoice. It also includes a url to download the actual document.

List all documents of an invoice

Get specific document

Document resource properties

Transactions

This resource lists all transactions that has occured on the invoice. The resource does not support "GET" on individual transactions, only listing of all transactions.
Property "typeName" is ment to be displayed directly "as is" in a customer portal, it is translated to a readable text in the language configured on the current company.

List all transactions that has occured on an invoice

Transaction resource properties

Active payment orders

This resource corresponds to an active / scheduled payment order placed against the specific account, the end-customer will be debited at the given executeDate.

Get active payment orders for an account

Active-payment-orders resource properties

Journal

This resource lists all events that has occured on the invoice, in a sorted timeline.

Get journal entries for the invoice

Journal resource properties

Register direct payment

operation for registration of direct payments against invoices

Register-direct-payment request properties

Settle-credit-invoice

operation to settle an existing credit invoice towards debit invoice. This operation is only be available/valid on credit-invoices

Settle-credit-invoice request properties

Remission

operation to allow partialy remission of the debt. Usually used if there is a small debt left on the invoice after a payment hade been done, and the remaining amount should be offered. 

remission request properties

Write-down

operation to allow partialy or full write-down of the debt. the reason/cause of the write-down should be specified (affects accounting)

Write-down request properties

Respite

Resource to create or view respite

Get respite

Create respite

Respite request properties

Active-disbursement-orders

View or create disbursement orders, only available for credit-invoices

Get active-disbursement-orders

Create disbursement order towards a norwegian bank account

Create disbursement order towards a international bank account (IBAN)

Create disbursement order towards a swedish bank account

Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"

Respite request properties

* One and only one of the specified objects can be set at each request 

Transfer-to-account

operation transfer current capital debt on the invoice to a provided account. This will close the invoice.

Transfer-to-account request properties

Generate-invoice-portal-link

Creates a new public available (no authorization needed) link to the targeted invoice. Default lifetime of a link is 120 days. Creating new links does not affect old links.

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Problem types