Invoice Lifecycle

The invoice lifecycle describes the end-to-end flow of a collection request — from creation by a biller, through delivery and payment, to reconciliation. This process is the core business flow of the Kulpay Collection API.

Participants

Participant	Role	Channel
Biller	Issues invoices and tracks payments	Portal Web / ERP Integration
Kulpay Collection API	Manages invoice lifecycle, routes payments, and triggers notifications	—
Payer (Customer)	Receives and pays invoices	Kulpay App / Bank / SIMO ERV
Payment Provider	Processes the payment transaction	Bank / SIMO ERV

Process Flow

Step-by-Step

Phase 1: Invoice Creation

1. Biller creates a collection request via the API or the bill-created webhook
2. The system generates a unique collection request ID
3. Collection method details are attached (SIMO ERV reference or interbank NIB)
4. A customer bill record is created with invoice metadata

API Endpoints:

• POST /v1/collection-requests — Create via API
• POST /v1/collection-requests/web-hook/bill-created — Create via webhook

Phase 2: Invoice Delivery

5. Based on the payer's delivery_method, the invoice is delivered:
   • SMS: Payment reference and amount sent to payer's phone
   • Email: Full invoice with payment link sent to payer's email
   • ERP: Invoice synced back to the biller's ERP system
   • Kulpay App: Push notification sent to the customer's Kulpay account
6. The bill-delivered webhook confirms delivery

API Endpoints:

• POST /v1/collection-requests/{id}/web-hook/bill-delivered — Delivery confirmation
• POST /v1/collection-requests/{id}/web-hook/kulpay — App notification

Phase 3: Customer Engagement

7. Customer opens/views the invoice
8. The bill-opened webhook tracks this event
9. The system updates the invoice status history

API Endpoints:

• POST /v1/collection-requests/{id}/web-hook/bill-opened — View tracking

Phase 4: Payment

10. Customer pays using one of the available methods:
    • Kulpay App: Direct in-app payment → triggers customer-paid webhook
    • SIMO ERV: Customer pays using entity number + reference at any bank or ATM
    • Bank Transfer: Customer transfers to the biller's NIB
11. For external payments (SIMO/bank), the payment is ingested via the Payment Ingest endpoint
12. The bill-paid webhook notifies the biller

API Endpoints:

• POST /v1/collection-requests/{id}/web-hook/customer-paid — In-app payment
• POST /v1/payments/ingest — External payment ingestion
• POST /v1/collection-requests/{id}/web-hook/bill-paid — Payment notification

Phase 5: Reconciliation

13. The system matches the payment to the collection request
14. Reconciliation status is updated:
    • Matched: Payment amount matches the invoice → automatically reconciled
    • Unmatched: Discrepancy detected → flagged for manual review
15. Compliance and audit fields are updated (paid_at, reconciled_at)

Invoice Status Values

Status	Description
pending	Invoice created, not yet delivered or paid
delivered	Invoice delivered to payer
viewed	Payer has opened/viewed the invoice
in_process	Payment is being processed
paid	Payment confirmed and reconciled
failed	Payment attempt failed

Payment Reconciliation Status

Status	Description
matched	Payment amount matches invoice — automatically reconciled
unmatched	Payment discrepancy — requires manual review

Related API Endpoints

Endpoint	Purpose
POST /v1/collection-requests	Create a new invoice
GET /v1/collection-requests/{id}	Check invoice status
GET /v1/payments	List payments for a collection request
POST /v1/payments/ingest	Ingest external payment
See Webhooks & Events	All webhook endpoints

Business Rules

• Invoices can have multiple collection methods (both SIMO ERV and interbank)
• The delivery_method on the payer determines how the invoice is sent
• Partial payments are tracked but require manual reconciliation
• All invoices include compliance fields (payer NUIT, issuer NUIT) for regulatory requirements
• Invoice metadata includes fx_rate for cross-currency scenarios
• IVA (Value-Added Tax) is tracked in the financial details