Collect payables
Learn how to collect an incoming invoice to start the payable flow.
Overview
There are several ways to collect payables into Monite:
- Create a payable via API by providing the amount, currency, and other details.
- Upload an invoice in PDF, PNG, or JPEG formats via API.
- Send an invoice in PDF, PNG, or JPEG formats by email to the entity’s mailbox.
When a payable is created from a PDF, PNG, or JPEG file, Monite’s OCR service automatically extracts the invoice information from the file and a new payable is created with the extracted data fields accordingly. The file property of the payable contains the file metadata and the link to access the original source file.
About Monite OCR
Monite OCR uses top-notch Optical Character Recognition (OCR) algorithms to pull text from payables.
- The OCR process is asynchronous and the processing time may vary according to the document size. The webhook
ocr_finishedis triggered once the OCR has finished processing the file and storing the extracted data into a payable. - The field
payable.ocr_statusreflects the current status of the OCR process of a payable. Its possible values areprocessing,error, andsuccess. - The maximum image file size is 20 MB.
- The maximum email size is 25 MB (including all attachments).
- Files with dimensions smaller than 400x400 px are not considered payables, thus, they are not processed.
- PDF files must have at least one page with dimensions bigger than 400x400 px to be considered a payable, otherwise, they are not processed.
- Multipage PDF files can have up to 100 pages.
- Monite’s OCR service is not executed if the format of the uploaded document is not supported or the number of pages exceeds 10. Therefore, no invoice information is stored. In this case, only the information about the file is stored.
- You can configure the system to avoid the creation of duplicated payables based on the information obtained by the OCR.
Covered languages
While this is not an exhaustive list, Monite OCR guarantees tested coverage for the following languages:
- Arabic
- Bulgarian
- Catalan
- Chinese
- Czech
- Danish
- Dutch
- English
- Estonian
- Finnish
- French
- Georgian
- German
- Greek
- Hebrew
- Hungarian
- Italian
- Japanese
- Latvian
- Lithuanian
- Norwegian
- Polish
- Portuguese
- Romanian
- Russian
- Serbian
- Slovak
- Slovenian
- Spanish
- Swedish
- Thai
- Turkish
- Ukrainian
Create a payable from data
If you already have the invoice data (amount in minor units, currency, vendor information, and other details) stored somewhere as individual attributes, you can create a payable with these attributes by calling POST /payables.
You can provide the base64-encoded contents of the original invoice file in the field base64_encoded_file:
Notes:
- The
file_namefield is optional. If omitted, it defaults to"default_file_name". - If the settings are configured to automatically set
suggested_payment_term, this object can be omitted from the request body. - The fields
subtotalandtotal_amountof the payable are automatically calculated based on the values of the line items, therefore, they are read-only and appear only in the response schema. This feature can be disabled in the partner’s settings by callingPATCH /settingspassing the fieldenable_line_itemsasfalse(the default value istrue). Onceenable_line_itemsis disabled, the fieldsamount,subtotal,tax, andtax_amountof thepayableobject become editable during its creation and update, as they will no longer be calculated/re-calculated based on line items.
The successful response returns the id assigned to this payable, along with the information passed in the request. You can use this id in other API calls to update the data of this payable or trigger status transitions:
Automatic calculation of due date
If the values of the fields payment_terms.final_term and issued_at are provided in the payable, the due_date will be automatically calculated based on issued_at plus the number of days defined by payment_terms.final_term.number_of_days.
For example, if issued_at equals to 2023-06-15 and payment_terms.term_final.number_of_days equals to 10, the due_date will be automatically set to 2023-06-25.
In any other case, the due_date supplied by the user is stored in the payable. The payment_terms and issued_at fields have priority in the calculation of the due_date, even if thedue_date is supplied by the user.
The automatic calculation of the due_date happens when the payable is parsed by the OCR, created with data, or updated.
Suggested payment date
Once the payable is created, Monite automatically fills the payable’s field suggested_payment_term with a suggestion for the payment date and corresponding discount, if available, based on its payment terms (represented by the field payment_terms). When the payable’s issued_at or payment_terms fields are updated, the value for the suggested_payment_term is recalculated.
It is possible to choose the payment term (term_1, term_2, or term_final) to be suggested as default by setting the field payment_priority in the entity’s settings to one of these values:
-
working_capital: Selects the term with the latest possible payment target. -
bottom_line: Selects the term with the highest discount. -
balanced: Selects the intermediate term, that is, a balance between duration and drawn discount.
The suggested_payment_term will be calculated based on the field issued_at added by the term_X.number_of_days. Note that this suggestion does not affect the invoice’s due date, which remains the same.
Change the payment priority
To update the payment_priority of in the entity’s settings, call PATCH /entities/{entity_id}/settings, passing the new payment_priority in the body:
Automatic recalculation with credit notes
When a related credit note transitions from the status approve_in_progress to approved, the associated payable undergoes automatic recalculation. This ensures that the payable reflects the updated amounts and maintains consistency across related records.
The amount_with_credit_notes of the payable is recalculated using the total_amount of the credit note. After the recalculation is complete, the status of the related credit note is updated to applied.
Attach file
You can attach an invoice file to an existing payable, in any status, by calling POST /payables/{payable_id}/attach_file:
The provided file is then returned in the file field on the payable object.
Notes:
- The uploaded file is stored only for reference purposes.
- The file is not processed by the OCR or validated, therefore, the users need to ensure that the information in the file is correct.
- If the payable already has a file attached, an error is returned when trying to attach another one.
Cancel duplicated payables automatically
You can configure the system to avoid the creation of duplicated payable based on the information obtained by the OCR.
To enable this feature, send a PATCH request to the /settings endpoint, setting the payable.allow_cancel_duplicates_automatically field to true:
This way, once the counterpart is successfully auto-linked and the OCR identifies the invoice number inside the payable, the system verifies if there is any invoice with an identical counterpart ID (counterpart_id field) and invoice number (document_id field) for the given entity. If a payable with this information is found, i.e. the payable already exists, the system automatically sends the newly created payable to the canceled status.
To ensure the automatic cancellation of duplicated payables, it is imperative to have the auto-linking feature enabled.
Upload files via API
You can upload invoices in the PDF, PNG, or JPG format to Monite by calling POST /payables/upload_from_file. The maximum file size is 20 MB:
In return, you receive back the 201 Created response with id and other parameters:
You will also receive a webhook indicating that this payable resource has been created:
Note that at this stage the payable resource is incomplete and waiting for the results of the OCR service, which automatically scans the details from the uploaded invoice and maps the information from the invoice to the corresponding data field in the system.
When the OCR scanning is finished (this might take up to 5-7 minutes), you will receive the payable.ocr_finished webhook event:
Now, you can call GET /payables/{payable_id} to retrieve the results of the OCR scanning:
The other_extracted_data field in the response contains individual text labels and values extracted by OCR.
You can use this data to review and double-check the recognized text, but keep in mind that the structure of this object can change or even be null depending on the OCR results and various types of invoices:
Some comments about the line_items field:
unit: This can be any string that describes the units involved. It can be “m”, “h”, “items”, or anything else. It does not affect any numerical values.quantity: The number of items in float format, for example,0.25or10.0. The quantity is used to calculate the total amount and subtotal of the line item and the overall payable.unit_price: The price per unit expressed in minor unit of currency. This value influences the total amount and subtotal of the line item and the overall invoice.description: The description of the line item.total_excl_vat: The total amount before taxes that equals toquantity * unit_price. It is also measured in minor units and its value is used to calculate the total amount of the line item and the overall invoice.vat_percentage: The taxes as a percentage, expressed in minor units, for example,1900represents 19%. This value influences the total amount of the line item and the overall invoice ( = subtotal + applying taxes).
Send payables by email
Each entity has a dedicated mailbox in Monite to which the payables can be sent. The entity or entity user can send invoices as attachments in PDF, PNG, or JPEG format to this mailbox (the maximum file size is 20 MB).
The Monite OCR service scans the information inside each email’s attachments. Then, Monite automatically creates a draft payable invoice for each occurrence found. The email of the sender of these files is saved in the field sender of the invoice.
To find the mailbox assigned to a specific entity, call GET /v1/mailboxes:
The successful response contains information about the mailbox:
By default, the automatically created mailboxes belong to the Monite domain (the web address that comes after @ in an email address), but the partners can set up their own email domain for better convenience.
Uploading already paid payables
Uploaded payables that are already paid can be automatically recognized as such for automatic payment approval. Once the payable is recognized as paid, its status will be changed to paid or partially paid according to the this rule:
- If the value of the
amount_paidis greater or equal to theamount_to_pay, the payable status is automatically changed to thepaidstatus. - If the value of the
amount_paidis greater than0and the value of theamount_paidis greater or equals to theamount_to_pay, the payable status is automatically changed to thepartially_paidstatus.
To enable this behavior, set the field skip_approval_for_paid_invoice to true in the partner settings:
The skip_approval_for_paid_invoice default value is false.
Automatic matching of purchase orders with payables
Every time a payable is created or updated, Monite automatically tries to link this payable to its corresponding purchase order, which is already created in the system. The conditions for the purchase order autolinking to be performed are:
- The counterpart name on the payable must match, with a certain tolerance, the counterpart name on the purchase order.
- The line items` name and price on the payable must match those on the purchase order.
- The total amount of the payable or unit price for the line items on the payable must match those on the purchase order.
Once the corresponding purchase order is found, its ID is added to the payable.purchase_order_id field. If more than one applicable purchase order is found, the most recently created is selected.
The automatic matching is enabled by default. To disable this behavior, call PATCH /entities/{entity_id}/settings, passing the field allow_purchase_order_autolinking as false in the body.
The payable can also be manually matched by calling PATCH /payables/{payable_id}, passing the purchase_order_id in the body.
Tolerance match
The matching is performed considering these tolerance rules:
- Minor variations in the counterparts` names are accepted (e.g., “Ltd” vs. “Limited”).
- The billed quantity may vary slightly within a small allowable range.
- The total amount of the payable or the unit price on the payable may exceed the agreed-upon price by 5%.
Payables that do not meet the exact or tolerance match criteria require a manual review. This process includes:
- Checking for typos or data entry errors.
- Verifying explanations for discrepancies (e.g., price changes, shipping fees).