Order settlement status and invoice close-out

Reference

Two statuses describe where an order's money stands. The order's settlement status says whether the merchant has been paid. The status of the order's financial transaction says where the payment is in its lifecycle, and it reaches Settled only after the merchant's VAT invoice has been matched.

Overview#

Purchase, work and refuel orders all carry the same settlement status, settlement date and last-updated time. The platform sets the settlement status from the order's payment: when the payment completes or fails, the order follows. The order's financial transaction has its own status, which moves from Paid to Settled when the VAT invoice is matched. The two statuses answer different questions, change at different moments and can differ for a while. Where both fit in the money path is shown on Order-to-cash flow.

Order settlement status#

stateDiagram-v2
    state "Not recorded" as none
    state "Pending" as pending
    state "Settled" as settled
    state "Failed" as failed
    state "Disputed" as disputed
    none --> pending: completed, wallet payment created
    none --> settled: completed on B2B-Direct
    none --> failed: no payment route
    pending --> settled: payment completes
    pending --> failed: payment fails
    failed --> settled: replacement payment completes
    none --> disputed: platform team
    pending --> disputed: platform team
    settled --> disputed: platform team
    failed --> disputed: platform team
    disputed --> pending: platform team
    disputed --> settled: platform team
    disputed --> failed: platform team

Transaction status#

Each order's payment is recorded as one financial transaction. These are the statuses it takes on the order rails:

Invoice close-out#

The VAT invoice for an order is always issued by the merchant, outside the platform. The platform records that an invoice is owed and whether it arrived. It never issues one.

1. Invoice requested. When the transaction becomes Paid, the platform records that the merchant owes a VAT invoice for it.
2. Invoice matched. When the merchant's VAT invoice is fetched and matched to the transaction, the transaction moves from Paid to Settled and the request is marked as issued, linked to that invoice.

The two steps can happen in either order. If the invoice has already been matched when the transaction becomes Paid, the transaction settles at that moment. On a Petrolimex static-QR refuel, the matched invoice completes the order, so payment and close-out happen together. How VAT invoices are fetched and matched: Invoice match statuses.

An invoice request has one of four statuses: Requested, Issued, Failed or Cancelled. A request stays Requested until the invoice arrives. The platform raises no alert on an invoice that has not arrived, because it can take days.

Rules#

• Only a paid transaction can settle. If an invoice is matched to a transaction that is still Pending or is Cancelled, the transaction keeps its status. A pending one settles later, once it is paid.
• Settling happens once. A second invoice or a repeated match against a settled transaction changes nothing.
• Close-out moves no money. Matching the invoice changes only the transaction's status and the invoice request. It does not touch the wallet, the reservation or the payment, and it sends no notification.
• Invoice matching does not change the order's settlement status. The order's settlement status follows the payment only.
• One open invoice request per transaction. A request that failed can be raised again.

Where you see it#

• The purchase order detail page has a Merchant settlement card with Status, Settlement date and Last updated. It sits directly above the Finance card.
• The Finance card on purchase, work and refuel order pages shows the transaction status, its payments and its invoices. See The Finance card on order pages.
• The merchant's purchase order page has a payment summary with Operations confirmation, Settlement status, Settlement date and Last updated. While any of these is missing, it shows "Payment information incomplete - please check back in a few minutes."
• Work and refuel orders carry the same settlement status, but their detail pages do not show it.

Edge cases#

• Two "Settled" labels on one page. On a purchase order, the Merchant settlement card and the Finance card can both say Settled, or only one of them can. The first means the merchant was paid. The second means the invoice was matched as well. When an order has a replacement payment, the Finance card can also show a Settled amount: the total of completed payments, beside what is still outstanding.
• Failed payment replaced. A replacement for a failed payment that then completes moves the order from Failed to Settled. While the replacement is on its way, the order still shows Failed. See Re-issue a failed payment.
• Cancelled B2B-Direct order. The obligation is voided and the credit it used is restored. A paid or settled obligation is never voided.

Related#

• Order-to-cash flow
• Settlement rails for orders
• Purchase and work order statuses
• The Finance card on order pages
• Transactions, money movements and ledger entries