Skip to main content

Collection Request Service

Manages collection requests (invoices) for the Kulpay Collection API. Collection requests represent invoices or bills issued by a business to a payer, with support for multiple collection methods, payer details, and full invoice metadata.

Create Collection Request​

POST /v1/collection-requests

Creates a new collection request (invoice) for a payer.

Request Body:

{
  "description": "Fatura mensal de servicos de contabilidade",
  "collection_method_ids": ["cm_mpesa_001", "cm_emola_002"],
  "amount": {
    "currency": "MZN",
    "value": 15000.00
  },
  "payer": {
    "first_name": "Carlos",
    "last_name": "Mondlane",
    "legal_name": "Mondlane & Filhos Lda",
    "vat_number": "400123456",
    "address": {
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "street": "Av. 25 de Setembro",
      "line1": "Edificio 33, 4 Andar"
    },
    "contact": {
      "phone_number": "+258841234567",
      "email": "carlos@mondlane.co.mz"
    },
    "type": "business",
    "delivery_method": "email"
  },
  "third_party_reference": "ERP-INV-2025-0042",
  "metadata": {
    "department": "finance",
    "contract_id": "CTR-2025-100"
  }
}
FieldTypeRequiredDescription
descriptionstringNoHuman-readable description of the collection request
collection_method_idsstring[]YesIDs of collection methods to use for this request
amountobjectYesAmount object with currency and value
payerobjectYesPayer details (see Payer model)
third_party_referencestringNoExternal reference from your system (e.g., ERP invoice ID)
metadatamap<string,string>NoArbitrary key-value metadata

Response:

{
  "object": "collection_request",
  "id": "cr_abc12345",
  "collection_method_ids": ["cm_mpesa_001", "cm_emola_002"],
  "description": "Fatura mensal de servicos de contabilidade",
  "bill_info": {
    "bill_id": "bill_mz_98765",
    "bill_number": "KULPAY-2025-00042",
    "status": "pending",
    "due_date": "2025-02-28T00:00:00Z"
  },
  "amount": {
    "currency": "MZN",
    "value": 15000.00
  },
  "collection_method_details": [
    {
      "collection_method_id": "cm_mpesa_001",
      "name": "M-Pesa",
      "type": "mobile_money",
      "status": "active"
    },
    {
      "collection_method_id": "cm_emola_002",
      "name": "e-Mola",
      "type": "mobile_money",
      "status": "active"
    }
  ],
  "payer": {
    "first_name": "Carlos",
    "last_name": "Mondlane",
    "legal_name": "Mondlane & Filhos Lda",
    "vat_number": "400123456",
    "address": {
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "street": "Av. 25 de Setembro",
      "line1": "Edificio 33, 4 Andar"
    },
    "contact": {
      "phone_number": "+258841234567",
      "email": "carlos@mondlane.co.mz"
    },
    "type": "business",
    "delivery_method": "email"
  },
  "third_party_reference": "ERP-INV-2025-0042",
  "status": "pending",
  "metadata": {
    "department": "finance",
    "contract_id": "CTR-2025-100"
  },
  "created_at": "2025-01-20T09:15:00Z"
}

Get Collection Request​

GET /v1/collection-requests/{id}

Retrieves a single collection request by ID.

Path Parameters:

ParameterTypeDescription
idstringCollection request ID (pattern: cr_*)

Response:

{
  "object": "collection_request",
  "collection_request": {
    "id": "cr_abc12345",
    "account_id": "acc_biz_001",
    "description": "Fatura mensal de servicos de contabilidade",
    "amount": {
      "currency": "MZN",
      "value": 15000.00
    },
    "payer": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "legal_name": "Mondlane & Filhos Lda",
      "vat_number": "400123456",
      "address": {
        "country": "MZ",
        "state_province": "Maputo",
        "city": "Maputo",
        "street": "Av. 25 de Setembro",
        "line1": "Edificio 33, 4 Andar"
      },
      "contact": {
        "phone_number": "+258841234567",
        "email": "carlos@mondlane.co.mz"
      },
      "type": "business",
      "delivery_method": "email"
    },
    "third_party_reference": "ERP-INV-2025-0042",
    "collection_method_details": [
      {
        "collection_method_id": "cm_mpesa_001",
        "name": "M-Pesa",
        "type": "mobile_money",
        "status": "active"
      }
    ],
    "invoice_metadata": {
      "invoice_number": "KULPAY-2025-00042",
      "issue_date": "2025-01-20T09:15:00Z",
      "due_date": "2025-02-28T00:00:00Z",
      "invoice_type": "standard",
      "source_channel": "api",
      "reference_number": "REF-MZ-00042",
      "payment_link": "https://pay.kulpay.co.mz/inv/cr_abc12345"
    },
    "financial_details": {
      "line_items": "Servicos de contabilidade - Janeiro 2025",
      "products_info": {
        "quantity": 1,
        "unit_price": 15000.00,
        "subtotals": 15000.00
      },
      "tax_info": {
        "iva": 16.0
      },
      "discount": 0.00,
      "total_amount": {
        "currency": "MZN",
        "value": 17400.00
      },
      "fx_rate": 1.0
    },
    "payment_reconciliation": {
      "payment_status": "pending",
      "payment_type": "mobile_money",
      "gateway_transaction_id": null,
      "reconciliation_status": "unmatched",
      "date_payment": null,
      "date_reconciliation": null
    },
    "integration_routing": {
      "source_system": "erp",
      "callback_url": "https://api.mondlane.co.mz/webhooks/kulpay"
    },
    "compliance_audit": {
      "payer_nuit": "400123456",
      "issuer_nuit": "500987654",
      "invoice_validity": "2025-03-31T23:59:59Z",
      "attached_contract": "CTR-2025-100",
      "user_issuer": "usr_admin_001",
      "user_modifier": null,
      "user_remover": null,
      "issued_at": "2025-01-20T09:15:00Z",
      "viewed_at": null,
      "paid_at": null,
      "reconciled_at": null
    },
    "biller": {
      "account_id": "acc_biz_001",
      "business_name": "TechServ Mocambique Lda",
      "logo": {
        "file_id": "file_logo_techserv",
        "file_bucket": "logos",
        "file_link": "/files/logos/file_logo_techserv"
      },
      "contact": {
        "phone_number": "+258821000000",
        "email": "facturacao@techserv.co.mz"
      },
      "issuer_nuit": "500987654",
      "billing_address": {
        "country": "MZ",
        "state_province": "Maputo",
        "city": "Maputo",
        "street": "Rua da Imprensa",
        "line1": "Nr. 256, RC"
      }
    },
    "status": "pending",
    "created_at": "2025-01-20T09:15:00Z",
    "updated_at": "2025-01-20T09:15:00Z"
  }
}

List Collection Requests​

GET /v1/collection-requests

Lists all collection requests with pagination.

Query Parameters:

ParameterTypeDefaultDescription
page_sizeinteger50Max results per page (max: 100)
page_tokenstring-Token for next page

Response:

{
  "object": "list",
  "items": [
    {
      "id": "cr_abc12345",
      "account_id": "acc_biz_001",
      "description": "Fatura mensal de servicos de contabilidade",
      "amount": {
        "currency": "MZN",
        "value": 15000.00
      },
      "payer": {
        "first_name": "Carlos",
        "last_name": "Mondlane",
        "legal_name": "Mondlane & Filhos Lda",
        "type": "business",
        "delivery_method": "email"
      },
      "status": "pending",
      "created_at": "2025-01-20T09:15:00Z",
      "updated_at": "2025-01-20T09:15:00Z"
    },
    {
      "id": "cr_def67890",
      "account_id": "acc_biz_001",
      "description": "Renda do escritorio - Fevereiro 2025",
      "amount": {
        "currency": "MZN",
        "value": 45000.00
      },
      "payer": {
        "first_name": "Ana",
        "last_name": "Machel",
        "legal_name": "Machel Properties Lda",
        "type": "business",
        "delivery_method": "sms"
      },
      "status": "paid",
      "created_at": "2025-01-18T14:30:00Z",
      "updated_at": "2025-01-25T11:00:00Z"
    }
  ],
  "error": null
}

List Collection Requests by Phone Number (Unsecured)​

GET /v1/kulpay/collection-requests/list-by-phone-number/{phone_number}

Retrieves all collection requests associated with a payer's phone number.

Note: This endpoint is unsecured -- designed for Kulpay mobile app integration. Do not expose on public networks without additional application-level controls.

Path Parameters:

ParameterTypeDescription
phone_numberstringPayer's phone number in E.164 format (e.g., +258841234567)

Query Parameters:

ParameterTypeDefaultDescription
page_sizeinteger50Max results per page (max: 100)
page_tokenstring-Token for next page

Response:

{
  "object": "list",
  "items": [
    {
      "id": "cr_abc12345",
      "description": "Fatura mensal de servicos de contabilidade",
      "amount": {
        "currency": "MZN",
        "value": 15000.00
      },
      "status": "pending",
      "created_at": "2025-01-20T09:15:00Z"
    }
  ],
  "error": null
}

Get Collection Request (Unsecured)​

GET /v1/kulpay/collection-requests/get-request/{id}

Retrieves a single collection request by ID without authentication.

Note: This endpoint is unsecured -- designed for Kulpay mobile app integration. Do not expose on public networks without additional application-level controls.

Path Parameters:

ParameterTypeDescription
idstringCollection request ID (pattern: cr_*)

Response:

{
  "object": "collection_request",
  "collection_request": {
    "id": "cr_abc12345",
    "account_id": "acc_biz_001",
    "description": "Fatura mensal de servicos de contabilidade",
    "amount": {
      "currency": "MZN",
      "value": 15000.00
    },
    "payer": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "legal_name": "Mondlane & Filhos Lda",
      "vat_number": "400123456",
      "address": {
        "country": "MZ",
        "state_province": "Maputo",
        "city": "Maputo",
        "street": "Av. 25 de Setembro",
        "line1": "Edificio 33, 4 Andar"
      },
      "contact": {
        "phone_number": "+258841234567",
        "email": "carlos@mondlane.co.mz"
      },
      "type": "business",
      "delivery_method": "email"
    },
    "third_party_reference": "ERP-INV-2025-0042",
    "collection_method_details": [
      {
        "collection_method_id": "cm_mpesa_001",
        "name": "M-Pesa",
        "type": "mobile_money",
        "status": "active"
      }
    ],
    "invoice_metadata": {
      "invoice_number": "KULPAY-2025-00042",
      "issue_date": "2025-01-20T09:15:00Z",
      "due_date": "2025-02-28T00:00:00Z",
      "invoice_type": "standard",
      "source_channel": "api",
      "reference_number": "REF-MZ-00042",
      "payment_link": "https://pay.kulpay.co.mz/inv/cr_abc12345"
    },
    "financial_details": {
      "line_items": "Servicos de contabilidade - Janeiro 2025",
      "products_info": {
        "quantity": 1,
        "unit_price": 15000.00,
        "subtotals": 15000.00
      },
      "tax_info": {
        "iva": 16.0
      },
      "discount": 0.00,
      "total_amount": {
        "currency": "MZN",
        "value": 17400.00
      },
      "fx_rate": 1.0
    },
    "payment_reconciliation": {
      "payment_status": "pending",
      "payment_type": "mobile_money",
      "gateway_transaction_id": null,
      "reconciliation_status": "unmatched",
      "date_payment": null,
      "date_reconciliation": null
    },
    "compliance_audit": {
      "payer_nuit": "400123456",
      "issuer_nuit": "500987654",
      "invoice_validity": "2025-03-31T23:59:59Z",
      "attached_contract": "CTR-2025-100",
      "user_issuer": "usr_admin_001",
      "user_modifier": null,
      "user_remover": null,
      "issued_at": "2025-01-20T09:15:00Z",
      "viewed_at": null,
      "paid_at": null,
      "reconciled_at": null
    },
    "biller": {
      "account_id": "acc_biz_001",
      "business_name": "TechServ Mocambique Lda",
      "logo": {
        "file_id": "file_logo_techserv",
        "file_bucket": "logos",
        "file_link": "/files/logos/file_logo_techserv"
      },
      "contact": {
        "phone_number": "+258821000000",
        "email": "facturacao@techserv.co.mz"
      },
      "issuer_nuit": "500987654",
      "billing_address": {
        "country": "MZ",
        "state_province": "Maputo",
        "city": "Maputo",
        "street": "Rua da Imprensa",
        "line1": "Nr. 256, RC"
      }
    },
    "status": "pending",
    "created_at": "2025-01-20T09:15:00Z",
    "updated_at": "2025-01-20T09:15:00Z"
  }
}

Update Collection Request​

PUT /v1/collection-requests/{id}

Updates an existing collection request. Only provided fields are updated.

Path Parameters:

ParameterTypeDescription
idstringCollection request ID (pattern: cr_*)

Request Body:

{
  "name": "Fatura actualizada - servicos de contabilidade",
  "type": "recurring",
  "account_id": "acc_biz_002",
  "details": {
    "collection_method_id": "cm_mpesa_001",
    "name": "M-Pesa",
    "type": "mobile_money",
    "status": "active"
  }
}
FieldTypeRequiredDescription
namestringNoUpdated name for the collection request
typestringNoUpdated type classification
account_idstringNoReassign to a different account
detailsobjectNoUpdated collection method detail (see CollectionMethodDetail)

Response:

{
  "object": "collection_request",
  "collection_request": {
    "id": "cr_abc12345",
    "name": "Fatura actualizada - servicos de contabilidade",
    "type": "recurring",
    "account_id": "acc_biz_002",
    "status": "pending",
    "created_at": "2025-01-20T09:15:00Z",
    "updated_at": "2025-01-22T16:45:00Z"
  },
  "error": null
}

Delete Collection Request​

DELETE /v1/collection-requests/{id}

Deletes a collection request from the system.

Path Parameters:

ParameterTypeDescription
idstringCollection request ID (pattern: cr_*)

Response:

{
  "object": "collection_request",
  "error": null
}

Data Models​

Payer​

Represents the individual or business being billed.

FieldTypeRequiredDescription
first_namestringYesPayer's first name
last_namestringYesPayer's last name
legal_namestringYesLegal business name (for business payers)
vat_numberstringYesVAT / NUIT number
addressobjectNoPayer's address (see Address)
contactobjectNoPayer's contact information (see Contact)
typestringYesPayer type (e.g., business, individual)
delivery_methodstringYesHow to deliver the invoice: email, sms, or erp

Address​

FieldTypeDescription
countrystringISO 3166-1 alpha-2 country code (e.g., MZ)
state_provincestringState or province name
citystringCity name
streetstringStreet name
line1stringAdditional address line (building, floor, suite)

Contact​

FieldTypeDescription
phone_numberstringPhone number in E.164 format
emailstringEmail address

InvoiceMetadata​

Invoice-level metadata attached to the collection request.

FieldTypeDescription
invoice_numberstringSystem-generated invoice number
issue_datestringISO 8601 date when the invoice was issued
due_datestringISO 8601 payment due date
invoice_typestringInvoice type (e.g., standard, proforma, credit_note)
source_channelstringChannel that originated the request (e.g., api, portal, erp)
reference_numberstringInternal reference number
payment_linkstringURL where the payer can complete payment

FinancialDetails​

Detailed financial breakdown for the collection request.

FieldTypeDescription
line_itemsstringDescription of line items
products_infoobjectProduct details: quantity, unit_price, subtotals
tax_infoobjectTax details: iva (Mozambique VAT percentage)
discountnumberDiscount amount applied
total_amountobjectFinal amount with currency and value
fx_ratenumberForeign exchange rate applied (1.0 for local currency)

PaymentAndReconciliation​

Tracks payment status and reconciliation state.

FieldTypeDescription
payment_statusstringpending, in_process, paid, or failed
payment_typestringPayment method type used
gateway_transaction_idstringTransaction ID from the payment gateway
reconciliation_statusstringmatched or unmatched
date_paymentstringISO 8601 date when payment was received
date_reconciliationstringISO 8601 date when reconciliation completed

Payment Status Values​

StatusDescription
pendingInvoice issued, awaiting payment
in_processPayment initiated, processing
paidPayment received in full
failedPayment attempt was unsuccessful

Reconciliation Status Values​

StatusDescription
matchedPayment has been reconciled with the invoice
unmatchedPayment has not yet been reconciled

ComplianceAndAudit​

Regulatory compliance and audit trail fields.

FieldTypeDescription
payer_nuitstringPayer's NUIT (tax identification number)
issuer_nuitstringIssuer's NUIT (tax identification number)
invoice_validitystringISO 8601 date when the invoice expires
attached_contractstringReference to an attached contract
user_issuerstringUser ID who created the collection request
user_modifierstringUser ID who last modified the collection request
user_removerstringUser ID who deleted the collection request
issued_atstringISO 8601 timestamp when the request was issued
viewed_atstringISO 8601 timestamp when the payer first viewed the request
paid_atstringISO 8601 timestamp when payment was completed
reconciled_atstringISO 8601 timestamp when reconciliation completed

AccountDetails (Biller)​

Information about the business that issued the collection request.

FieldTypeDescription
account_idstringBiller's account ID
business_namestringRegistered business name
logoobjectBusiness logo with file_id, file_bucket, and file_link
contactobjectBiller contact: phone_number and email
issuer_nuitstringBiller's NUIT (tax identification number)
billing_addressobjectBiller's address (see Address)