Payables lifecycle

Draft

Status value: draft

This is the initial status for all uploaded payables that have any of the required fields set as null during their creation. The required fields are:

• amount
• currency
• document_id
• due_date
• issued_at

Apart from the required fields, the following requirements are also mandatory:

• The payable must have at least one line item.
• The value of line_items[].tax, if set, must complement the line_items[].subtotal and match with the line_items[].total.
• The sum of all line_items[].subtotal must be equal to the payable’s subtotal.

It is possible to upload payables with any set of fields or even with all fields empty, but only after the payable is filled with all required fields, its status is automatically changed to new.

📘

By connecting to an external accounting system, additional requirements will become mandatory when creating a payable, in addition to the standard mandatory fields. The additional requirements are:

• All line items in the payable must be linked to the ledger accounts, i.e. each line item must have the ledger_account_id field specified. The ledger account ID can be obtained by making a GET request to the /ledger_accounts endpoint after the accounting integration has been set up.

• Make sure that the accounting system has the same tax rate value (e.g. 18%) as described on each one of the tax values in all line items of the payable.

Customize the list of required fields

You can change and customize the list of required fields that are necessary to move a payable to the new state by sending a PUT request to the /payables/validations endpoint passing the new list of required fields as an array of strings:

curl -X PUT 'https://api.sandbox.monite.com/v1/payables/validations' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -d '{
       "required_fields": [
         "description",
         "sender",
         "tax"
       ]
      }'

The successful response returns the new list of required fields:

{
  "required_fields": [
    "description",
    "sender",
    "tax"
  ]
}

📘

Notes

• A successful request overwrites the existing list of required fields and replaces them with the newly defined array of required fields.
• If the file_id field is specified as required, including a file for the payable becomes mandatory.
• If a composed field is specified, e.g. line_items, a minimum of one item will be required.
• It is possible to specify fields of different levels, e.g. line_items.subtotal.
• If the custom required fields list is not specified, the default validation is applied.
• To list the current required fields, send a GET request to the /payables/validations endpoint.
• To remove the custom required fields and return the validation to the default one, send a POST request to the /payables/validations/reset endpoint. The default behavior will be applied to the future payables created.
• Payables that have already passed the new status will not be affected by newly updated required fields.

Validate mandatory fields

To understand what information is missing to move a payable from draft to the new state, send a POST request to the /payables/{payable_id}/validate endpoint:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/validate' \
  -H 'X-Monite-Version: 2024-01-31' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d ''

The successful response returns the fields that need to be filled for the transition:

{
  "id": "d1d5da69-9c1b-42fc-a1d2-9dcc4c3c691f",
  "validation_errors": [
    {
      "loc": [
        "tax_amount"
      ],
      "msg": "none is not an allowed value",
      "type": "type_error.none.not_allowed"
    },
    {
      "loc": [
        "line_items"
      ],
      "msg": "ensure this value has at least 1 items",
      "type": "value_error.list.min_items",
      "ctx": {
        "limit_value": 1
      }
    }
  ]
}

New

Status value: new

If the uploaded payable already contains all essential fields, its initial status is directly set to new. Only payables in the new status can be sent for approval.

Once the entity user validates the payable, the payable's status changes to approve_in_progress.

The entity users can also directly confirm the payable for payment from the new status.

Canceled

Status value: canceled

The canceled payables are the ones that were not validated during the entity user review.

For example, if the entity user uploads the wrong file or the document is not compliant with regulations, this payable can be canceled before being sent for approval.

There is no possible status change when a payable is canceled.

Approval pending

Status value: approve_in_progress

After the initial validation, the payable follows the approval policy defined for the entity. The following approval paths are enabled by default:

• Paid documents: Under paid status, the payable no longer requires approval.
• Immediate approval: Entity users with a specific role are enabled to select any payable and approve it immediately. The payable status changes to waiting_to_be_paid.
• Approval flows: All payables that are neither paid nor approved follow the approval workflow:
  • On refusal, the payable status changes to rejected.
  • On approval, the payable status changes to waiting_to_be_paid.

In case the workflow started for the payable requires the approval of specific entity users, reminder notifications are sent by email containing information about the payable and the link to perform the approval.

Refused

Status value: rejected

The payables that are refused during the approve_in_progress status. By adding a reason for the refusal, the entity user who uploaded the invoice knows what went wrong.

There is no possible status change when a payable is refused.

Approved

Status value: waiting_to_be_paid

Once the approval process is finished, the invoice is ready to be paid. At this point, the user who uploaded the invoice is notified by an email containing information about the invoice to be paid and a link to the payment provider.

Entity users can pay invoices through Monite or external payment channels. If paying through Monite, the invoice is moved to the paid status automatically. If an external payment channel is used, entity users must manually convert the invoice to the paid status.

Partially paid

Status value: partially_paid

Payables can be marked as partially paid by setting the remaining amount_paid with the partial payment value, in minor units.

Paid

Status value: paid

Entity users can access all paid documents to view any details and export these documents for accounting reasons.