How it works

The actors, the resources and how they change over time.

This page is the map. The other concept pages go deeper: Sessions and callbacks, Invoice intents and offers and Attachments.

The actors

Actor	Role
You, the partner	Your product calls the API. You hold a partner key.
Your client	A company that wants to sell its invoices. It is represented by an account.
The end user	A person at your client who signs contracts and answers KYC questions in a browser.
The customer	The company that owes the money, the debtor of an invoice.
Invoier	Checks, prices and finances the invoices.

The resources

Text

Partner key
   └─ Account  ──────────────  your client
        ├─ Account session      a hosted flow for the end user (onboarding, KYC renewal)
        ├─ Customer             a debtor, identified by organisation number
        ├─ Invoice intent       "what would financing this invoice look like?"
        │     └─ Invoice        the invoice you decided to sell
        │           └─ Attachment   the invoice PDF
        └─ Document             contract documents

The account of your client is the one that sells, so you use the account's key, or your own key on behalf of the account, for customers, intents and invoices.

Everything is asynchronous

When you create something, you get an answer straight away, but the work continues in the background. A resource has a status that moves forward over time. You find out about it by polling the resource.

There are no webhooks yet. They are planned. Until they arrive, the ways to follow changes are:

• Polling. Fetch the resource now and then and read its status. The sections below say what to wait for.
• Session callbacks. These are not webhooks. They are browser redirects that bring the end user back to your application, see Sessions and callbacks. You decide what your application does when the end user arrives, and you are responsible for not sending them around in circles.

How often to poll depends on the resource. Invoice intents settle within about a minute, so poll every few seconds for that long. Accounts and sessions are waiting on people and on back-office checks, so poll less often, for example every ten seconds while the end user is watching a screen and every few minutes in the background. Always stop polling when the resource reaches a final status.

Statuses

Read these as maps of what can happen. A resource only moves in the directions shown.

Account

stateDiagram-v2
    [*] --> CREATED
    CREATED --> PREPARING
    PREPARING --> AWAITING_ONBOARDING: eligible
    PREPARING --> DISABLED: cannot be onboarded
    AWAITING_ONBOARDING --> ONBOARDING: onboarding session completed
    ONBOARDING --> ENABLED
    ENABLED --> DISABLED: you disable it
    DISABLED --> ENABLED: you enable it

Session

stateDiagram-v2
    [*] --> CREATED
    CREATED --> PROVISIONING: end user opens the url (sandbox: immediately)
    PROVISIONING --> READY
    PROVISIONING --> FAILED
    READY --> ACTIVE: the flow starts
    ACTIVE --> COMPLETED
    ACTIVE --> CANCELED
    CANCELED --> ACTIVE: end user tries again
    READY --> EXPIRED
    ACTIVE --> EXPIRED
    CANCELED --> EXPIRED

A session can also be DELETED by you. COMPLETED, EXPIRED, FAILED and DELETED are final.

Invoice intent

stateDiagram-v2
    [*] --> COLLECTING_OFFERS
    COLLECTING_OFFERS --> COMPLETED: after about a minute at most

Some setups report PENDING_FINANCING_OFFERS and COLLECTING_FINANCING_OFFERS instead of COLLECTING_OFFERS. Treat every status other than COMPLETED as "still working".

Invoice

stateDiagram-v2
    [*] --> AWAITING_ATTACHMENTS
    AWAITING_ATTACHMENTS --> READY: the invoice PDF has arrived
    READY --> review_and_financing
    review_and_financing --> FINANCED
    review_and_financing --> NOT_FINANCED

review_and_financing is not a status. It stands for several statuses that you can see on the way, such as IN_REVIEW, PENDING_FINANCING and CONFIRMING_AGREEMENT. See the invoiceStatus field in the reference for all of them. You can DELETE an invoice, which makes it DELETED.

Who can see what

Resources belong to the account that created them. You only ever see your own, and asking for someone else's looks the same as asking for one that does not exist (404).

Next

• Onboarding an account is the first thing to build.
• Selling an invoice is the second.