> ## 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](https://alguna.com/docs/integrations/payments/stripe.md) or [ACH](https://alguna.com/docs/integrations/payments/ach.md)), or when you record one taken outside Alguna. See [How Alguna Works](https://alguna.com/docs/concepts/how-alguna-works.md) 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 |
| `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](https://alguna.com/docs/api-reference/v2/webhooks.md) 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.

> [!WARNING]
>
> 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](https://alguna.com/docs/invoices/refunds.md).

***

## 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](https://alguna.com/docs/api-reference/v2/2026-04-01/payments/get-a-payment.md) and [List payments](https://alguna.com/docs/api-reference/v2/2026-04-01/payments/list-payments.md) 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

> **[Refunds](https://alguna.com/docs/invoices/refunds.md)**
>
> Return money against a payment.

> **[Surcharges](https://alguna.com/docs/invoices/surcharges.md)**
>
> Charge a card or bank-transfer fee on top of the amount settled.

> **[Collections](https://alguna.com/docs/collections/overview.md)**
>
> Chase invoices that have not been paid.

> **[Dunning](https://alguna.com/docs/collections/dunning.md)**
>
> Retry failed payments and escalate.

> **[Webhooks](https://alguna.com/docs/api-reference/v2/webhooks.md)**
>
> React to payment events in your own systems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.