Invoicing, payments & credit

This area follows the financial commitments of resellers and secures sales (cahier §4.7, §5 home, §5.3, §8, §11, §14.2, reference screen 1). Invoices are generated from orders; payments arrive by cash on delivery, transfer, CCP, BaridiMob or on credit; partial payments are allocated to invoices; credit is controlled at checkout and at confirmation; credit notes settle returns, after-sales refunds and cancelled invoices. It is run by the Responsable finance in the back-office (BO); resellers see their balance, invoices and payments in the app and web (RA, RW). The server's billing module owns Invoice, InvoiceLine, Payment, PaymentAllocation, CreditAccount, CreditLimitChange and CreditNote (V1); contracts on API › Finance and API › Back-office finance; statuses on Lifecycles › Invoice and Payment. Financial data is visible only with finance.* permissions (ACL-04).

ID	Requirement	Release	Priority	Source	Apps
FIN-01	Invoices generated from orders with legal mentions and PDF; statuses unpaid, partially paid, paid, overdue, cancelled	V1	MUST	§4.7	API · BO · RA · RW
FIN-02	Payment methods: cash on delivery, bank transfer, CCP, BaridiMob, credit	V1	MUST	§4.7	API · RA · RW · BO
FIN-03	Payment recording in the back-office and payment declaration with proof by the reseller	V1	MUST	§4.7	API · BO · RA · RW
FIN-04	Partial payments and allocation to invoices (reconciliation)	V1	SHOULD	§4.7	API · BO
FIN-05	Basic credit control: ceiling, used and available credit checked at checkout	V1	MUST	§4.7, §5.3, §8	API · BO · RA · RW
FIN-06	Detailed credit: payment terms, due dates, automatic blocking or approval when exceeded	V2	SHOULD	§4.7, §14.2	API · BO
FIN-07	Automatic reminders and unpaid alerts	V2	SHOULD	§4.7	API · BO
FIN-08	Credit notes (avoirs) for returns and after-sales refunds; payment receipts	V1	SHOULD	§4.7	API · BO · RA
FIN-09	Accounting exports and financial reports	V2	SHOULD	§4.7, §11	API · BO
FIN-10	Reseller finance view: balance, available credit, invoices, payments	V1	MUST	§5 (home), reference screen 1	RA · RW · API

Settings used in this areaCopy Anchor Link

RequirementsCopy Anchor Link

FIN-01 — Invoices with legal mentions, PDF and statusesCopy Anchor Link

Statement — The system shall issue one invoice per order when the order reaches the configured status, with the legal mentions and a PDF, and follow it through the statuses unpaid, partially paid, paid, overdue and cancelled.

Rules

1. The invoice is issued automatically when the order reaches billing.invoiceOn (default SHIPPED, crossing rule); one invoice per order in V1. Number FAC-YYYY-NNNNNN from NumberSequence, per year in Africa/Algiers, without gaps.
2. Content: HOCO's identity and legal identifiers (company name, address, RC, NIF, NIS, AI, bank details), the reseller's identity and identifiers when known, number, issue date, due date, order number, lines (reference, designation, quantity, unit price HT, discount, VAT rate, total HT), totals HT, VAT per rate and TTC (PRC-04), amount in words, payment method. The figures are the order's snapshot.
3. Due date = issue date + the credit account's term (default credit.defaultTermDays) for CREDIT orders, else + billing.dueDaysDefault.
4. Statuses (InvoiceStatus): UNPAID at issue; PARTIALLY_PAID and PAID from confirmed allocations and credit notes (FIN-04); OVERDUE set by the daily job at 00:30 Africa/Algiers when the due date has passed with a balance; CANCELLED.
5. An issued invoice is never edited. Cancelling (admin.invoices.cancel, finance.validate, reason required) is allowed while it has no confirmed allocation (409 INVOICE_HAS_PAYMENTS) and issues a credit note of the full amount (FIN-08); the number is never reused. A cancelled order cancels its unpaid invoice the same way.
6. The PDF (private GENERATED_DOCUMENT) is generated by the worker; regenerating it keeps the number and the amounts. Resellers list and open their invoices (invoices.list, invoices.get, RA-30, RW-13) and download the PDF (orders.document); the back-office lists all of them with filters (BO-44, finance.view).
7. Issue notifies the reseller (invoice.issued, inbox, and email with the PDF link when an address is known); overdue is visible to finance and on the reseller's balance.

Value	UI label (fr)	Meaning
UNPAID	Impayée
PARTIALLY_PAID	Partiellement payée
PAID	Payée
OVERDUE	En retard	Set by a daily job when dueDate passes with a balance.
CANCELLED	Annulée

Acceptance criteria

• Shipping CMD-2026-000158 issues FAC-2026-000123 with the order's totals and a due date 7 days later (cash on delivery).
• A credit order of a reseller with a 30-day term gets a due date 30 days after issue.
• A payment of half the amount moves the invoice to PARTIALLY_PAID; the rest moves it to PAID.
• At 00:30 the day after the due date, an invoice with a balance becomes OVERDUE.
• Cancelling an invoice that has a confirmed allocation returns 409 INVOICE_HAS_PAYMENTS; cancelling an unpaid one issues a full credit note.

Data — Invoice, InvoiceLine, NumberSequence, File, CreditNote, Order.

Interfaces

• Screens: RA-30 Invoices · BO-44 Invoices · RW-13 Invoices, payments & credit
• API: orders.document GET /orders/{orderId}/documents/{type} · invoices.list GET /invoices · invoices.get GET /invoices/{invoiceId} · admin.invoices.list GET /admin/invoices · admin.invoices.get GET /admin/invoices/{invoiceId} · admin.invoices.cancel POST /admin/invoices/{invoiceId}/cancel

Notes / open points — Legal mentions and the stamp duty on cash payments (droit de timbre) are D-21; go-live is blocked while undecided.

FIN-02 — Payment methodsCopy Anchor Link

Statement — The system shall offer at checkout the payment methods cash on delivery, bank transfer, CCP, BaridiMob and credit, as enabled by HOCO and allowed for the reseller.

Rules

1. Methods (PaymentMethod): CASH_ON_DELIVERY, BANK_TRANSFER, CCP, BARIDIMOB, CREDIT; the enabled set is payments.enabledMethods.
2. cart.checkoutOptions returns each method with allowed and, when not allowed, the reason: method disabled, no credit line (limit 0), credit account blocked, or available credit below the cart total (« Crédit insuffisant : disponible 12 500,00 DA »).
3. Checkout with a method not allowed answers 422 PAYMENT_METHOD_NOT_ALLOWED (details.reason: METHOD_DISABLED, NO_CREDIT_LINE, CREDIT_BLOCKED); credit over the limit follows FIN-05.
4. For transfer, CCP and BaridiMob, the confirmation screen and the invoice show HOCO's account details (RIB, CCP account, RIP) and the order number to quote; the reseller then declares the payment with a proof (FIN-03). Whether HOCO waits for the verified payment before shipping is a back-office decision, not a checkout rule.
5. The method is frozen on the order; the back-office may change it only through a controlled modification recorded in the change log.

Value	UI label (fr)	Meaning
CASH_ON_DELIVERY	Paiement à la livraison
BANK_TRANSFER	Virement bancaire
CCP	CCP
BARIDIMOB	BaridiMob
CREDIT	Crédit (paiement différé)

Acceptance criteria

• With CREDIT disabled in the settings, checkout options show it not allowed with METHOD_DISABLED, and a checkout with it returns 422 PAYMENT_METHOD_NOT_ALLOWED.
• A reseller with limit 0 sees Crédit not allowed with NO_CREDIT_LINE.
• After a checkout by transfer, RA-20 shows HOCO's RIB and the order number.

Data — Setting, CreditAccount, Order (payment method).

Interfaces

• Screens: RA-18 Checkout · RA-31 Payments & payment declaration · RW-07 Checkout & confirmation
• API: cart.checkoutOptions GET /cart/checkout-options

Notes / open points — Methods offered at launch and to whom are D-03.

FIN-03 — Payments recorded by the back-office and declared by resellersCopy Anchor Link

Statement — The system shall let finance record payments received, let resellers declare payments with a proof, and let finance confirm or reject each declaration.

Rules

1. A Payment has a number PAY-YYYY-NNNNNN, a method, an amount, a payment date, a reference (transfer or receipt number), an optional proof file, a status (PaymentStatus: PENDING_VERIFICATION, CONFIRMED, REJECTED) and a source (BACK_OFFICE, RESELLER_DECLARATION, DELIVERY_COLLECTION).
2. Recording (BO-45, admin.payments.record, finance.create): method enabled (422 PAYMENT_METHOD_DISABLED otherwise; credit is not a payment method), amount, date, reference, allocations (FIN-04); a payment recorded by finance is CONFIRMED.
3. Declaration (RA-31, RW-13, payments.declare, Idempotency-Key required): method BANK_TRANSFER, CCP or BARIDIMOB, amount, date, reference, a PAYMENT_PROOF file (at most 10 MB) and optionally the invoices or order it pays; status PENDING_VERIFICATION. A pending account cannot declare (403 ACCOUNT_PENDING_VALIDATION). A declaration with the same reference, amount and method as another within 90 days is flagged as a possible duplicate for the verifier.
4. Cash collected at delivery creates a DELIVERY_COLLECTION payment PENDING_VERIFICATION (DLV-03), confirmed by finance when the cash is handed in.
5. Verification (admin.payments.verify, finance.validate): confirm (with allocations) or reject with a reason from PAYMENT_REJECT_REASON; a payment already verified answers 409. Only confirmed payments change balances and credit.
6. The reseller sees each declaration's status and is notified of its verification (push and inbox); new declarations reach finance live.

Value	UI label (fr)	Meaning
PENDING_VERIFICATION	À vérifier
CONFIRMED	Confirmé
REJECTED	Rejeté

Acceptance criteria

• A reseller declares a CCP payment of 20 000,00 DA with a receipt photo: PAY-… is PENDING_VERIFICATION, visible in BO-45 À vérifier, and the invoice balance is unchanged.
• Finance confirms it allocated to FAC-2026-000123: the invoice becomes PARTIALLY_PAID and the reseller is notified.
• Rejecting without a reason returns 400 VALIDATION_FAILED; a rejected declaration never changes the balance.
• A declaration without proof file returns 400 VALIDATION_FAILED.

Data — Payment, PaymentAllocation, File (PAYMENT_PROOF), Invoice, ReferenceItem (PAYMENT_REJECT_REASON), NumberSequence.

Interfaces

• Screens: RA-31 Payments & payment declaration · BO-45 Payments & declarations · RW-13 Invoices, payments & credit
• API: payments.list GET /payments · payments.declare POST /payments/declarations · admin.payments.list GET /admin/payments · admin.payments.record POST /admin/payments · admin.payments.verify POST /admin/payments/{paymentId}/verification

Notes / open points — Proof requirements for declarations are D-26.

FIN-04 — Partial payments and allocation to invoicesCopy Anchor Link

Statement — The system should allocate each confirmed payment to one or more invoices, accept partial payments, and keep any remainder as the reseller's credit balance.

Rules

1. A PaymentAllocation links a payment to an invoice with an amount; the sum of a payment's allocations never exceeds its amount, and an allocation never exceeds the invoice's balance (422 otherwise); cancelled invoices cannot receive allocations.
2. Without explicit allocations, a confirmed payment is allocated automatically to the reseller's open invoices, oldest due date first; an unallocated remainder is kept as unallocated credit of the reseller and allocated to the next invoices.
3. Finance re-allocates a payment (admin.payments.allocate, finance.update); every change is historised and journaled.
4. Invoice statuses are recomputed from confirmed allocations and credit notes: balance = TTC − allocations − credits.
5. Allocations and unallocated credit lower the used credit (FIN-05) at once.

Acceptance criteria

• A confirmed payment of 30 000,00 DA without explicit allocation pays the oldest invoice (20 000,00 DA) in full and 10 000,00 DA of the next one.
• An allocation of 15 000,00 DA on an invoice with a balance of 10 000,00 DA is refused.
• A payment larger than every open invoice leaves the remainder as unallocated credit shown on the reseller's balance.

Data — PaymentAllocation, Payment, Invoice, CreditAccount.

Interfaces

• Screens: BO-45 Payments & declarations
• API: admin.payments.record POST /admin/payments · admin.payments.allocate PUT /admin/payments/{paymentId}/allocations

FIN-05 — Credit control at checkout and confirmationCopy Anchor Link

Statement — The system shall control credit orders against each reseller's credit limit — at checkout and again at the back-office confirmation — using one definition of used and available credit.

Rules

1. A CreditAccount per reseller holds the limit (default credit.defaultLimit = 0, meaning no credit), a blocked flag, the term in days and a policy (INHERIT, BLOCK, REQUIRE_APPROVAL). Changes (admin.credit.update, finance.administer, reason required) write CreditLimitChange rows; lowering a limit under the used credit is allowed (available becomes 0, existing orders are not cancelled).
2. Used credit = Σ balance of the reseller's UNPAID, PARTIALLY_PAID and OVERDUE invoices (whatever their method) + Σ total TTC of its CREDIT orders not yet invoiced and not refused or cancelled − unallocated credit. Available = max(0, limit − used).
3. At checkout with CREDIT: no credit line or a blocked account → 422 PAYMENT_METHOD_NOT_ALLOWED; total above available → 422 CREDIT_LIMIT_EXCEEDED (details: limit, used, available, required) under policy BLOCK, or the order is created and held PENDING with reason CREDIT_OVER_LIMIT under REQUIRE_APPROVAL. Concurrent credit checkouts of one reseller are serialised (row lock on the credit account).
4. At confirmation the credit control is re-run (ORD-05): exceeded or blocked → 422 CREDIT_LIMIT_EXCEEDED / CREDIT_ACCOUNT_BLOCKED unless a finance.validate holder records a credit override with a reason (journaled OVERRIDE).
5. Assisted orders and back-office orders apply the same control. Refused or cancelled orders release their exposure at once.
6. The reseller sees limit, used and available credit in RA-29 / RW-13 and the home tile (FIN-10); finance sees the exposure breakdown in BO-46.

Acceptance criteria

• Limit 5 000 000, open invoices 2 100 000, no uninvoiced credit order: a credit cart of 3 974 600 returns 422 CREDIT_LIMIT_EXCEEDED with available: 2900000.
• Under REQUIRE_APPROVAL the same checkout creates the order PENDING with CREDIT_OVER_LIMIT; a commercial administrator without finance.validate cannot confirm it with an override.
• Two simultaneous credit checkouts that together exceed the available credit: one succeeds, the other gets 422 CREDIT_LIMIT_EXCEEDED.
• Changing a limit without reason returns 422 REASON_REQUIRED; with a reason a CreditLimitChange row records before, after and the actor.

Data — CreditAccount, CreditLimitChange, Invoice, Order, Payment, AuditLog.

Interfaces

• Screens: RA-18 Checkout · RA-29 Balance & credit · BO-08 Finance dashboard · BO-46 Credit accounts · RW-07 Checkout & confirmation
• API: cart.checkoutOptions GET /cart/checkout-options · cart.checkout POST /cart/checkout · finance.summary GET /finance/summary · admin.orders.validate POST /admin/orders/{orderId}/validate · admin.credit.get GET /admin/credit-accounts/{resellerId} · admin.credit.update PATCH /admin/credit-accounts/{resellerId}

Notes / open points — Over-limit policy and eligibility are D-04 and D-29 (defaults: BLOCK, limit 0).

FIN-06 — Detailed credit (V2)Copy Anchor Link

Statement — The system should, in V2, manage payment terms and due dates per reseller and block or require approval automatically when credit is exceeded or overdue.

Rules

1. Terms per reseller (e.g. 30 or 60 days, end of month) drive due dates; a grace period before blocking is configurable.
2. Automatic blocking: a reseller with invoices overdue beyond the grace period has its credit blocked until paid, and is notified; unblocking is automatic on payment or manual by finance.
3. Approval workflow for over-limit orders with a finance decision recorded on the order.

Acceptance criteria

• With a 30-day term and 5 days of grace, a reseller with an invoice overdue 6 days cannot check out on credit until it is paid.

Data — CreditAccount, Invoice, CreditLimitChange.

Interfaces

• Screens: BO-47 Overdue & reminders
• API: admin.credit.update PATCH /admin/credit-accounts/{resellerId}

Notes / open points — V2 (SRV-32).

FIN-07 — Automatic reminders and unpaid alerts (V2)Copy Anchor Link

Statement — The system should, in V2, remind resellers of invoices coming due and overdue, and alert finance about unpaid invoices.

Rules

1. Reminder schedule (e.g. D−3, D+1, D+7, D+15) by push, SMS and — with the WhatsApp Business API — WhatsApp, each sent once and logged as a PaymentReminder.
2. Finance sees the overdue board (BO-47) with amounts, days overdue and reminder history.

Acceptance criteria

• An invoice due on 10 Dec gets one reminder on 7 Dec and one on 11 Dec if unpaid; both appear in its reminder history.

Data — V2 PaymentReminder, Invoice.

Interfaces

• Screens: BO-47 Overdue & reminders
• API: admin.finance.overdue GET /admin/finance/overdue

Notes / open points — V2 (SRV-32).

FIN-08 — Credit notes and payment receiptsCopy Anchor Link

Statement — The system should issue credit notes (avoirs) for accepted returns, after-sales refunds and cancelled invoices, and a receipt for each confirmed payment.

Rules

1. A CreditNote has a number AV-YYYY-NNNNNN (per year, no gaps), an origin (RETURN, AFTER_SALES, INVOICE_CANCELLATION), lines, HT, VAT per rate and TTC amounts computed from the original order line prices, and a PDF.
2. Issued automatically: by a return reception for the accepted units (ORD-13), by an after-sales resolution CREDIT_NOTE (SUP-04), by an invoice cancellation for the full amount (FIN-01).
3. A credit note is allocated first to the related invoice's balance; the rest becomes the reseller's unallocated credit, usable against later invoices and lowering used credit (FIN-05). Cash refunds are handled outside the platform in V1 and recorded as a note.
4. A receipt (PDF, the payment's PAY- number) is available for every confirmed payment, downloadable by the reseller and finance.
5. The reseller is notified (credit_note.issued) and downloads credit notes from RA-30 / RW-13; the back-office lists them with the invoices.

Acceptance criteria

• Receiving a return of 3 accepted units at 41 650 TTC issues AV-2026-000004 of 124 950 allocated to the order's invoice balance.
• Cancelling an unpaid invoice of 3 074 960 issues a credit note of the same amount with origin INVOICE_CANCELLATION.
• A confirmed payment offers a downloadable receipt bearing its PAY- number.

Data — CreditNote, Invoice, PaymentAllocation, Payment, File, NumberSequence.

Interfaces

• Screens: none dedicated
• API: admin.returns.receive POST /admin/returns/{returnId}/reception · admin.invoices.cancel POST /admin/invoices/{invoiceId}/cancel

Notes / open points — tasks.json still lists FIN-08 under the V2 task SRV-32 as well; the V1 work is done in SRV-20.

FIN-09 — Accounting exports and financial reports (V2)Copy Anchor Link

Statement — The system should, in V2, export sales, payments and credit notes in the format of HOCO's accounting software and provide financial reports.

Rules

1. Exports per period: sales journal (invoices and credit notes per VAT rate), payments journal, reseller balances — in the format agreed with HOCO's accountant (CSV or XLSX), from BO-48 (finance.export, journaled).
2. An exported period can be locked so that its documents cannot be cancelled afterwards.

Acceptance criteria

• Exporting November produces one file listing every invoice and credit note of the month with HT, VAT and TTC per rate, whose totals match the finance dashboard.

Data — Invoice, CreditNote, Payment, ExportJob.

Interfaces

• Screens: BO-48 Accounting exports
• API: admin.finance.export POST /admin/finance/exports

Notes / open points — V2; the accounting system is D-34.

FIN-10 — Reseller finance viewCopy Anchor Link

Statement — The system shall show each reseller their balance due, credit limit and available credit, invoices and payments, on the home screen and in a finance section.

Rules

1. finance.summary: balance due (Σ open invoice balances), of which overdue, credit limit, used and available credit, unallocated credit, next due date and the number of declarations awaiting verification.
2. Home tiles (reference screen 1, catalog.home): Solde and Crédit disponible (credit tile hidden when the limit is 0); RA-27 account hub links to the finance screens.
3. RA-29 / RW-13: balance and credit; RA-30: invoices with status filter and PDF; RA-31: payments and declarations with their status and the « Déclarer un paiement » action (FIN-03).
4. Only the reseller's own data (ACL-03); figures equal the back-office's for the same reseller.

Acceptance criteria

• A reseller with two open invoices of 10 000,00 and 5 000,00 DA sees Solde 15 000,00 DA on the home and in RA-29.
• A reseller with limit 0 sees no Crédit disponible tile.
• The available credit shown equals finance.summary.available and BO-46's figure for that reseller.

Data — Invoice, Payment, PaymentAllocation, CreditAccount, CreditNote.

Interfaces

• Screens: RA-09 Home · RA-27 Account hub · RA-29 Balance & credit · RA-30 Invoices · RW-02 Home · RW-13 Invoices, payments & credit
• API: catalog.home GET /catalog/home · finance.summary GET /finance/summary · invoices.list GET /invoices

Error codesCopy Anchor Link