> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Payments
> How Alguna records money received, what each payment status means, and how a payment is attributed across invoices
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](/docs/integrations/payments/stripe) or [ACH](/docs/integrations/payments/ach)), or when you record one taken outside Alguna. See [How Alguna Works](/docs/concepts/how-alguna-works) for how payments, invoices and corrections relate.
***
## Statuses
| `status` | Meaning |
| ----------------------- | ------------------------------------------------------------ |
| `pending_client_action` | The customer must complete an action, for example 3-D Secure |
| `pending_authorization` | Awaiting authorization by the processor |
| `processing` | Being processed |
| `completed` | Succeeded |
| `settled` | Funds settled |
| `failed` | The payment failed |
| `voided` | The payment was voided |
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](/docs/api-reference/v2/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.
```json theme={null}
"allocations": [
{ "invoice_id": "inv_abc123", "amount": "999.00" },
{ "invoice_id": "inv_def456", "amount": "500.00" }
]
```
`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](/docs/invoices/refunds).
***
## Reading payments
Payments are created by the billing flow rather than by the API. Two endpoints read them:
```bash cURL theme={null}
curl https://api.alguna.io/payments/pay_abc123 \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01"
```
```python Python theme={null}
import os, requests
response = requests.get(
"https://api.alguna.io/payments/pay_abc123",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
},
)
payment = response.json()
```
See [Get a payment](/docs/api-reference/v2/2026-04-01/payments/get-a-payment) and [List payments](/docs/api-reference/v2/2026-04-01/payments/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.
***
## Related
Return money against a payment.
Chase invoices that have not been paid.
Retry failed payments and escalate.
React to payment events in your own systems.