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 open status; step 1 finds it, and gotactl events trigger invoice.issued issues one if the list is empty.
  • A test API key holding invoices:read, payments:read and payments:write.
  • A webhook endpoint, or gotactl webhooks listen running (see Listen to webhook events).

1. Find an open invoice#

bash
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.

bash
curl -sS "$BUSINESS_API/payment-methods" \
  -H "Authorization: Bearer $API_KEY"

Example response:

json
{
  "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.

bash
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:

json
{
  "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:

json
{
  "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.

Next steps#