Payments

Subscription and invoice payments. Initiate an M-Pesa STK-push mobile payment (via the Lipad gateway) and list a customer's invoices.

2 endpoint(s)

POST Request M-Pesa Mobile Payment (STK Push) {{url}}/payment/mobile ▸

Trigger an M-Pesa STK push prompt on a parent's phone, asking them to enter their PIN to complete a payment (e.g. paying a subscription invoice).

Request Body

amount (number, required, min 0)
phone_number (string, required): The phone to send the STK push to.
parent_id (string UUID, required): The parent this payment is attributed to.

Notes

The actual charge is initiated via the registry using the parent's linked third-party (the registry) customer ID.
A successful response only means the prompt was sent — it does not confirm the parent completed payment.

Response

The STK-push initiation result (data); the customer gets an M-Pesa prompt on their phone. The final payment status arrives later via the payment callback, not in this response.

Auth

Bearer token

Request Body

{
    "parent_id": "35438f0b-b488-4ea0-b69d-73e214910ab9",  // Parent (guardian account) UUID
    "phone_number": "+254725544432",  // Phone number, international format (e.g. +2547XXXXXXXX)
    "amount": 1  // Amount in KES
}

Sample Response (422 Unprocessable Content)

{
    "status": 200,
    "data": [],
    "message": "Payment requested successfully"
}

GET List Invoices {{url}}/payment/invoices ▸

Retrieve a paginated list of invoices, optionally scoped to a specific parent.

Query Parameters

per_page (integer, optional, default 10, max 20)
parent_id (string UUID, optional): Restrict to one parent's invoices; omit for an org-wide view.
status (string, optional): Invoice status.
date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD", filters by due date.

Notes

Each invoice includes its line items (invoice_items).

Response

Paginated list of invoices (data) with meta.

Auth

Bearer token

Request Body

{
    "status": "PENDING", //only use: PENDING, PAID, FAILED, CANCELLED
    "parent_id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e",
    "per_page": 10,
    "page": 1
}

Sample Response (200 OK)

{
    "data": [
        "id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e"
        "parent": {
            "id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e"
            "first_name": "John",
            "last_name": "Smith",
        },
        "total_amount": "2026-002",
        "due_date": "14th Jan 2026",
        "issue_date": "14th Jan 2026",
        "status":"Pending",
        "invoice_items": [
        {
            "type":"Wristband",
            "description": "Wristband purchase for Peter Kimani",
            "amount": 1500.00,
            "created_at": "14th Jan 2026"
        },
        {
            "type":"Subscription",
            "description": "First month subscription for Peter Kimani",
            "amount": 200.00,
            "created_at": "14th Jan 2026"
        }
        ],
    ],
    "links": {
        "first": "http://terrago.test/api/payment/invoices?page=1",
        "last": "http://terrago.test/api/payment/invoices?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://terrago.test/api/payment/invoices?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "path": "http://terrago.test/api/payment/invoices",
        "per_page": 10,
        "to": null,
        "total": 0
    },
    "status": 200,
    "message": "Invoices Retrieved Successfully"
}