Webhooks & Events

The Kulpay Collection API provides webhook endpoints to receive real-time notifications about collection request lifecycle events. Webhooks enable integration between biller systems, payment processors, and the Kulpay ecosystem.

Overview

Webhook Endpoints

All webhook endpoints accept POST requests with application/json content type.

Bill Created

POST /v1/collection-requests/web-hook/bill-created

Notifies the system when a new bill/invoice has been created by a biller. This webhook receives the full collection request data and creates the corresponding records in the system.

Request Body:

The request body is a full CollectionRequest object:

{
  "id": "cr_abc123",
  "account_id": "acc_xyz789",
  "description": "Monthly electricity bill - January 2026",
  "amount": {
    "currency": "MZN",
    "value": 4500.00
  },
  "payer": {
    "first_name": "João",
    "last_name": "Silva",
    "legal_name": "",
    "vat_number": "",
    "address": {
      "country": "Mozambique",
      "state_province": "Maputo",
      "city": "Maputo",
      "street": "Av. Eduardo Mondlane 1234"
    },
    "contact": {
      "phone_number": "+258840000001",
      "email": "joao.silva@email.com"
    },
    "type": "individual",
    "delivery_method": "sms"
  },
  "collection_method_details": [
    {
      "type": "simo_erv",
      "collection_method_id": "cm_def456",
      "reference_number": "123456789",
      "entity_number": "12345"
    }
  ],
  "invoice_metadata": {
    "invoice_number": "INV-2026-001234",
    "issue_date": "2026-01-15",
    "due_date": "2026-02-15",
    "invoice_type": "utility",
    "source_channel": "erp",
    "reference_number": "REF-001234"
  },
  "financial_details": {
    "line_items": "Electricity consumption - 350 kWh",
    "products_info": {
      "quantity": 1,
      "unit_price": 4500.00,
      "subtotals": 4500.00
    },
    "tax_info": {
      "iva": 0.0
    },
    "discount": 0.0,
    "total_amount": {
      "currency": "MZN",
      "value": 4500.00
    },
    "fx_rate": "1.0"
  },
  "biller": {
    "account_id": "acc_xyz789",
    "business_name": "EDM - Electricidade de Moçambique",
    "issuer_nuit": "400000001",
    "contact": {
      "phone_number": "+258840000000",
      "email": "billing@edm.co.mz"
    }
  },
  "status": "pending",
  "created_at": "2026-01-15T10:00:00Z"
}

Response: Empty (200 OK)

Bill Paid

POST /v1/collection-requests/{id}/web-hook/bill-paid

Notifies the system when a bill has been paid through an external channel (e.g., bank transfer, SIMO ERV payment).

Path Parameters:

Parameter	Type	Description
`id`	string	Collection request ID

Request Body:

The request body is a CustomerBill object:

{
  "id": "cr_abc123",
  "bill_id": "bill_pay789",
  "invoice_identification": {
    "invoice_number": "INV-2026-001234",
    "issue_date": "2026-01-15",
    "due_date": "2026-02-15",
    "invoice_type": "utility",
    "reference_number": "REF-001234"
  },
  "issuer_information": {
    "account_id": "acc_xyz789",
    "business_name": "EDM - Electricidade de Moçambique",
    "issuer_nuit": "400000001"
  },
  "payer_type": "individual",
  "payer": {
    "first_name": "João",
    "last_name": "Silva",
    "contact": {
      "phone_number": "+258840000001"
    },
    "type": "individual",
    "delivery_method": "sms"
  },
  "payment_options": {
    "payment_methods": "bank",
    "payment_terms": "net_30"
  },
  "status_history": {
    "invoice_status": "paid",
    "paid_at": "2026-01-20T14:30:00Z"
  },
  "created_at": "2026-01-15T10:00:00Z"
}

Response: Empty (200 OK)

Bill Opened

POST /v1/collection-requests/{id}/web-hook/bill-opened

Notifies the system when a customer has viewed/opened the bill. This is used for tracking invoice delivery and engagement.

Path Parameters:

Parameter	Type	Description
`id`	string	Collection request ID

Request Body:

Same CustomerBill structure as Bill Paid.

Response:

{
  "account_id": "acc_xyz789",
  "collection_request": {
    "id": "cr_abc123",
    "account_id": "acc_xyz789",
    "description": "Monthly electricity bill - January 2026",
    "amount": {
      "currency": "MZN",
      "value": 4500.00
    },
    "status": "viewed"
  }
}

Bill Delivered

POST /v1/collection-requests/{id}/web-hook/bill-delivered

Notifies the system when a bill has been successfully delivered to the payer (via SMS, email, or ERP).

Path Parameters:

Parameter	Type	Description
`id`	string	Collection request ID

Request Body:

{
  "id": "cr_abc123",
  "invoice_identification": {
    "invoice_number": "INV-2026-001234",
    "issue_date": "2026-01-15",
    "due_date": "2026-02-15",
    "invoice_type": "utility",
    "reference_number": "REF-001234"
  }
}

Response: Empty (200 OK)

Customer Paid

POST /v1/collection-requests/{id}/web-hook/customer-paid

Notifies the system when a Kulpay customer has paid a bill through the Kulpay mobile app. This webhook is triggered after the in-app payment is confirmed.

Path Parameters:

Parameter	Type	Description
`id`	string	Collection request ID

Request Body:

{
  "id": "cr_abc123",
  "customer_id": "cus_abc12345",
  "invoice_number": "INV-2026-001234",
  "reference_number": "REF-001234",
  "third_party_reference": "3PR-EDM-001234",
  "invoice_type": "utility",
  "paid_amount": {
    "currency": "MZN",
    "value": 4500.00
  },
  "paid_at": "2026-01-20T14:30:00Z",
  "transaction_reference": "txn_abc123",
  "gateway_transaction_id": "gw_txn_xyz789"
}

Field	Type	Required	Description
`id`	string	Yes	Collection request ID
`customer_id`	string	Yes	Kulpay customer who made the payment
`invoice_number`	string	Yes	Invoice number being paid
`reference_number`	string	Yes	Bill reference number
`third_party_reference`	string	Yes	External reference from the biller
`invoice_type`	string	Yes	Type of invoice
`paid_amount`	Amount	Yes	Amount paid (currency + value)
`paid_at`	timestamp	Yes	When the payment was made
`transaction_reference`	string	Yes	Internal transaction reference
`gateway_transaction_id`	string	Yes	Payment gateway transaction ID

Response: Empty (200 OK)

Kulpay Notification

POST /v1/collection-requests/{id}/web-hook/kulpay

Sends a notification to a Kulpay customer about a bill. This can be used to remind customers about pending bills or to deliver new invoices directly to their Kulpay app.

Path Parameters:

Parameter	Type	Description
`id`	string	Collection request ID

Request Body:

{
  "id": "cr_abc123",
  "customer_id": "cus_abc12345",
  "customer_bill_id": "bill_pay789",
  "title": "New bill from EDM",
  "info_msg": "You have a new electricity bill of 4,500.00 MZN due on February 15, 2026.",
  "sent_at": "2026-01-16T08:00:00Z"
}

Field	Type	Required	Description
`id`	string	Yes	Collection request ID
`customer_id`	string	Yes	Target Kulpay customer
`customer_bill_id`	string	Yes	Bill ID for viewing details in-app
`title`	string	Yes	Notification title
`info_msg`	string	Yes	Notification message body
`sent_at`	timestamp	Yes	When the notification was sent

Response: Empty (200 OK)

Webhook Event Flow

The typical lifecycle of a collection request through webhooks:

Event Summary

Event	Trigger	Direction	Description
`bill-created`	Biller creates invoice	Biller → API	New invoice ingested into the system
`bill-delivered`	Bill sent to payer	API → Biller	Confirmation that bill was delivered
`bill-opened`	Customer views bill	Kulpay App → API	Tracks bill engagement
`bill-paid`	Payment confirmed	Biller/Bank → API	External payment notification
`customer-paid`	In-app payment	Kulpay App → API	Kulpay customer payment
`kulpay`	System notification	API → Kulpay App	Push notification to customer

Overview​

Webhook Endpoints​

Bill Created​

Bill Paid​

Bill Opened​

Bill Delivered​

Customer Paid​

Kulpay Notification​

Webhook Event Flow​

Event Summary​

Overview

Webhook Endpoints

Bill Created

Bill Paid

Bill Opened

Bill Delivered

Customer Paid

Kulpay Notification

Webhook Event Flow

Event Summary