Payment Collection

The payment collection process describes how a business sets up collection methods, issues invoices, and receives payments through the Kulpay Collection API. This end-to-end flow covers the biller's perspective — from configuring payment channels to reconciling received payments.

Participants

Participant	Role	Channel
Biller (Business)	Configures collection methods and issues invoices	Portal Web / ERP
Kulpay Collection API	Routes invoices, processes payments, reconciles	—
Payer	Receives invoices and makes payments	Kulpay App / Bank / SIMO ERV
Payment Provider	Processes transactions (SIMO ERV / Interbank)	—

Process Flow

Step-by-Step

Phase 1: Collection Method Setup

Before issuing invoices, the biller must configure at least one collection method:

SIMO ERV Method

1. Biller registers a SIMO ERV collection method with their entity number
2. The system generates unique reference numbers for each invoice
3. Payers can pay at any bank or ATM using the entity number + reference

Interbank Method

4. Biller registers an interbank collection method with their NIB
5. Payers transfer funds directly to the biller's bank account

API Endpoints:

• POST /v1/collection-methods — Create a collection method
• GET /v1/collection-methods — List configured methods

Phase 2: Invoice Issuance

5. Biller creates a collection request specifying:
   • One or more collection method IDs
   • Invoice amount and currency
   • Payer details (name, contact, delivery method)
   • Optional: third-party reference, metadata, description
6. The system generates the collection request and attaches:
   • Reference numbers for SIMO ERV payments
   • NIB details for interbank transfers
   • Invoice metadata (invoice number, dates)
7. A customer bill is created for Kulpay-registered payers

API Endpoints:

• POST /v1/collection-requests — Create invoice
• GET /v1/collection-requests/{id} — View invoice details

Phase 3: Payment Processing

8. Invoice is delivered to the payer based on delivery_method:

   • SMS: Reference number and amount sent via text
   • Email: Full invoice document with payment link
   • ERP: Synced to biller's ERP for their own delivery
   • Kulpay App: Push notification to the customer

9. Payer makes payment through one of the available channels:

Channel	How It Works	Settlement
SIMO ERV	Payer enters entity number + reference at bank/ATM	Settled via SIMO clearing
Interbank	Payer transfers to biller's NIB	Direct bank transfer
Kulpay App	Payer pays in-app from Kulpay balance	Instant via Kulpay

Phase 4: Payment Ingestion & Reconciliation

10. Payments are captured in the system:
    • Kulpay App payments: Captured instantly via customer-paid webhook
    • External payments: Ingested via the Payment Ingest endpoint or bill-paid webhook
11. The system matches payments to collection requests using reference numbers
12. Reconciliation status is set:
    • Matched: Amount and reference match → auto-reconciled
    • Unmatched: Discrepancy found → flagged for review

API Endpoints:

• POST /v1/payments/ingest — Ingest external payment
• GET /v1/payments — List payments (filterable by collection_request_id, status, amount range)
• POST /v1/collection-requests/{id}/web-hook/customer-paid — In-app payment notification
• POST /v1/collection-requests/{id}/web-hook/bill-paid — External payment notification

Collection Method Comparison

Feature	SIMO ERV	Interbank
Identifier	Entity number + reference	NIB
Payment Channels	Bank, ATM, mobile banking	Bank transfer
Reference Tracking	Automatic (per-invoice reference)	Manual (by amount/date)
Installments	Configurable	Not supported
Reusable References	Configurable	N/A
Settlement Speed	1-2 business days	Same-day or next-day
Best For	Utility bills, recurring invoices	Large B2B payments

Payment Flow Diagram

Related API Endpoints

Endpoint	Purpose
POST /v1/collection-methods	Configure payment channels
GET /v1/collection-methods	List collection methods
POST /v1/collection-requests	Issue an invoice
GET /v1/collection-requests	List invoices
POST /v1/payments	Record a payment
GET /v1/payments	List and filter payments
POST /v1/payments/ingest	Ingest external payments
See Webhooks & Events	Payment lifecycle events

Business Rules

• Billers must have at least one active collection method before creating invoices
• Each invoice can use multiple collection methods simultaneously
• SIMO ERV references are unique per invoice (unless allow_reuses is enabled)
• Payment amounts in MZN (Mozambican Metical) by default
• IVA (VAT) is tracked per invoice for tax compliance
• The biller's NUIT and the payer's NUIT are recorded for audit purposes
• Payments are matched by reference number for SIMO ERV, and by amount + date for interbank
• See Invoice Lifecycle for the full invoice status flow
• See Merchant Onboarding for the account setup process