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.

Surcharges

Charge a card or bank-transfer fee on top of the amount settled.

Collections

Chase invoices that have not been paid.

Dunning

Retry failed payments and escalate.

Webhooks

React to payment events in your own systems.