Receive payments
Record payments confirmed outside the platform against an invoice, and learn about every payment, wherever it came from, through the payment.received and invoice.paid events.
What you will build#
A payment reaches a utility by one of three routes: a resident pays in a checkout session opened through the Consumer API, a payment connector reports its provider's confirmation, or someone confirms the money outside the platform (a counter, a bank transfer, your own collection system). Your integration does not need to know which route was taken: each one ends as a posted payment with a receipt, applied to invoices.
In this guide you record the third case through the API with POST /payments/confirm, and you build the confirmation all three share: the payment.received event once the payment is stored, and invoice.paid once the invoice balance reaches zero.
Prerequisites#
- A sandbox with at least one invoice in
openstatus; step 1 finds it, andgotactl events trigger invoice.issuedissues one if the list is empty. - A test API key holding
invoices:read,payments:readandpayments:write. - A webhook endpoint, or
gotactl webhooks listenrunning (see Listen to webhook events).
1. Find an open invoice#
curl -sS "$BUSINESS_API/invoices?status=open&limit=1" \
-H "Authorization: Bearer $API_KEY"
2. See which methods the utility accepts#
A payment can be recorded only with a method the utility configured and has switched on. The list comes from the utility's collection channels and from the methods its installed connectors declare; none of it is fixed in code. payments:read or payments:write is enough to read it.
curl -sS "$BUSINESS_API/payment-methods" \
-H "Authorization: Bearer $API_KEY"
Example response:
{
"payments_active": true,
"data": [
{
"code": "bank_transfer",
"channel": "bank_transfer",
"source": "channel",
"requires_reference": true,
"requires_phone": false,
"requires_shift": false,
"available": true
}
]
}
3. Record the payment against the invoice#
amount is in minor units, and idempotency_key makes sure a retry never creates a second payment. provider_reference is the reference from the bank, the mobile wallet or the counter slip.
curl -sS -X POST "$BUSINESS_API/payments/confirm" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"account_id":"act_3eQrF3JmTj2ZXpkFlbdO36UPXGP","invoice_id":"inv_3z9cS8ItYBqz0D66bvqNC7QSn8E","amount":185000,"currency":"MZN","method":"bank_transfer","provider_reference":"TRF-20261119-004812","confirmed_at":"2026-11-19T10:05:00Z","idempotency_key":"erp-collection-004812"}'
201 Created response, abridged:
{
"id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz",
"account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
"invoice_id": "inv_3z9cS8ItYBqz0D66bvqNC7QSn8E",
"amount_cents": 185000,
"currency": "MZN",
"method": "bank_transfer",
"provider_reference": "TRF-20261119-004812",
"receipt_number": "RCP-000058",
"status": "posted",
"paid_at": "2026-11-19T10:05:00Z"
}
4. Confirm on the webhook#
Do not treat the payment as settled on the HTTP response alone: the same event also arrives when the money comes from a resident checkout or a connector, and that is what lets you handle all three routes in one place. Subscribe to payment.received and invoice.paid. A payment.received body looks like this:
{
"id": "wev_3x6bknQybCmscpyDKTJXSdTOBT7",
"type": "payment.received",
"api_version": "v1",
"tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
"created_at": "2026-11-19T10:05:01Z",
"data": {
"resource_type": "payment",
"resource_id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz",
"attributes": {
"invoice_id": "inv_3z9cS8ItYBqz0D66bvqNC7QSn8E",
"customer_id": "cus_3Byj2A4oNoD4aVDMGLeWCWY5CWP",
"account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
"amount_cents": 185000,
"currency": "MZN",
"method": "bank_transfer",
"receipt_number": "RCP-000058"
},
"resource": { "type": "payment", "id": "pay_3dvlZQUZFQkYsjGOtWm37jocuyz", "sequence": 1 }
}
}
Test it#
Without creating anything by hand, gotactl events trigger payment.received posts a payment confirmed by the sandbox's simulated connector, and gotactl events trigger invoice.paid issues an invoice and pays it. To inspect payments, run gotactl payments get pay_3dvlZQUZFQkYsjGOtWm37jocuyz or gotactl payments list --limit 10, or open Payments in the dashboard and pick the payment to see its receipt number.
Common refusals: 400 with error_code payment.method_not_configured when the method is not configured or not switched on; 403 with capability.inactive while the utility's payments are not yet active; 400 with validation.must_be_positive for an amount of zero or less.