Skip to main content
A payment records money a customer has paid you. It is its own object with its own lifecycle, separate from the invoices it settles: a payment can cover one invoice, several invoices, or none at all when it comes from a checkout that has not been invoiced yet. Alguna decides what is owed and when; a payment provider moves the money. A payment is created when a provider takes it (for example Stripe or ACH), or when you record one taken outside Alguna. See How Alguna Works for how payments, invoices and corrections relate.

​
Statuses

The first three mean money is still in flight and the amount is not yet yours to count on. The rest are resolved outcomes. paid_at is set when the payment completes and failed_at when it fails. The payment.created and payment.updated webhooks fire as the payment is taken and on each status change, so you do not need to poll.

​
Attribution across invoices

A payment carries allocations: the invoices it was applied to and how much went to each.
allocations is authoritative — read it whenever you need to know what a payment settled.
The top-level invoice_id is deprecated. It is populated only when a payment covered exactly one invoice and is null otherwise, so code that reads it silently misses multi-invoice payments. Use allocations.
Amounts are tracked separately from the allocation split: amount is what was requested, amount_received what the provider actually took, and amount_refunded how much has since been returned by refunds.

​
Reading payments

Payments are created by the billing flow rather than by the API. Two endpoints read them:
See Get a payment and List payments for the full response and the filters available. external_id is the provider’s own identifier for the payment and external_url opens it in the provider’s dashboard — both useful when reconciling against a processor statement.

Refunds

Return money against a payment.

Collections

Chase invoices that have not been paid.

Dunning

Retry failed payments and escalate.

Webhooks

React to payment events in your own systems.