# 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](/docs/guides/listen-webhooks)).

## 1. Find an open invoice

```bash
curl -sS "$BUSINESS_API/invoices?status=open&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` starts with `inv_`. Note its `account_id`, `balance_cents` (the amount owed, in the currency's minor units) and `currency`.

## 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
    }
  ]
}
```

✓ Checkpoint: `payments_active` is `true` and at least one method has `"available": true`. Use its `code` in the next step, and honour `requires_reference`.

## 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"
}
```

✓ Checkpoint: `status` is `posted` and `receipt_number` is set. Sending the request again with the same `idempotency_key` returns `200` and the same `id`, with no new payment.

## 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 }
  }
}
```

✓ Checkpoint: your receiver logs `payment.received` carrying the `resource_id` from step 3 and, when the amount covered the balance, an `invoice.paid` whose attributes show `"status": "paid"` and `"balance_cents": 0`.

## 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

- [Build a resident app with payment checkout](/docs/guides/resident-app)
- [Connect a payment connector](/docs/guides/connect-connector)
- [Verify delivery signatures](/docs/webhooks/verify)
- [Issue invoices and credit notes](/docs/guides/issue-invoices)

