Payable status transitions

Overview

The chart below shows all the different ways that a payable can transition from status to status:

Once a payable is uploaded, its status is set to either draft (if any of the essential fields are missing) or new (if the uploaded payable already contains all essential fields during its creation).

After a payable in the draft status has all essential fields filled out, its status automatically changes to new.

This payable then needs to go through additional approval statuses before it is cleared for payment:

1. approval_in_progress
2. waiting_to_be_paid

The allowed status transitions depend on the current status of a payable.

Cancel a payable

Current status: new, approval_in_progress

A payable that is not confirmed during the entity user review can be canceled by calling POST /payables/{payable_id}/cancel:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/cancel' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

The successful response reflects the new status of the payable:

{
  ...
  "status": "canceled",
  ...
}

Start approval

Current status: new

Once an uploaded payable has been validated, the approval process is started by calling POST /payables/{payable_id}/submit_for_approval:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/submit_for_approval' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

The successful response reflects the new status of the payable:

{
  ...
  "status": "approval_in_progress",
  ...
}

The counterpart auto-linking and auto-creation may happen during this transition.

Confirm for payment

Current status: new, approval_in_progress

To confirm that a payable is ready to be paid, call POST /payables/{payable_id}/approve_payment_operation:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/approve_payment_operation' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The successful response reflects the new status of the payable:

{
  ...
  "status": "waiting_to_be_paid",
  ...
}

Reject

Current status: approval_in_progress

If an approver finds any mismatch or discrepancies in the payable, they can decline it by calling POST /payables/{payable_id}/reject:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reject' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The successful response reflects the new status of the payable:

{
  ...
  "status": "rejected",
  ...
}

Mark as paid

Current status: waiting_to_be_paid

Payables can be paid using the payment channels offered by Monite or through external payment channels. In the latter case, the invoice is not automatically marked as paid in the system and needs to be converted to the paid status manually.

To mark a payable as paid, call POST /payables/{payable_id}/mark_as_paid. Optionally, it is possible to pass the comment field in the request body, to describe how and when the invoice was paid:

curl -X 'POST https://api.sandbox.monite.com/v1/payables/{payable_id}/mark_as_paid' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{"comment": "Optional text that describes how and when the invoice was paid."}'

The successful response contains the ID of the user who marked the invoice as paid, the new status of the payable, and the comment:

{
  ...
  "marked_as_paid_with_comment": "Optional text that describes how and when the invoice was paid.",
  "marked_as_paid_by_entity_user_id": "71e8875a-43b3-434f-b12a-54c84c176ef3",
  "status": "paid",
  ...
}