Refunds

A refund returns money the customer has already paid. In Alguna a refund is always made against a payment, not against an invoice: it is processed by the payment provider that took the money (for example Stripe) and tracked as its own object with its own status. Use this page when you need to give money back, or to reconcile refunds that credit notes or the dashboard have triggered. Most refunds should start from a credit note: applying a credit note to a paid invoice with do_refund: true creates the refund for you and leaves the customer with a document explaining why. Create a refund directly only when no credit note is needed. See How Alguna Works for how payments, invoices, and corrections relate.

Statuses

`status`	Meaning
`pending`	Submitted to the payment provider, not yet settled
`succeeded`	The provider confirmed the money was returned
`failed`	The provider could not complete it; see `failure_reason`
`canceled`	Cancelled before completing

Settlement to the customer’s card or account takes as long as the provider and rail need — typically several business days for cards. The refund.updated webhook fires on each status change.

What happens to a paid invoice

Nothing. Refunding does not change the invoice’s status, and there is no refunded invoice status — an invoice is draft, upcoming, pending_approval, scheduled, processing, issued, paid, overdue, void or canceled, and one that was paid and then refunded stays paid. This is deliberate: the invoice is the record of what was billed and that it was settled at the time, and reversing it later does not make that untrue. The reversal is recorded elsewhere, and which record you create decides what the books show:

You want to	Do	Effect
Return money without changing what was billed	Refund the payment directly	A refund object against the payment. The invoice total and revenue are untouched
Reverse the charge itself and return the money	Credit note, then apply it with a refund	The credit note reduces what was owed and flows into revenue and tax; the refund returns the cash
Withdraw an invoice that should never have gone out	Void it	Only works on an `issued` or `overdue` invoice

A duplicate charge or a payment taken in error is the first row. A wrong price, an overcharge or a cancelled service is the second — reach for the credit note, because a bare refund leaves the invoice claiming revenue you have given back. Voiding is not an option once the invoice is paid: POST /invoices/{id}/void returns 400 for any status other than issued or overdue. Issue a credit note against it instead.

Because the invoice stays paid, “which of my paid invoices have been refunded?” is a question about refunds, not invoices: list refunds and match them to invoices through their payments. See Read refunds.

Refund through a credit note

Credit the invoice, then apply the credit note with a refund. The refund amount is the credit note total, and the credit note records last_refund_id. Full walkthrough on Credit Notes.

# 1. Credit two units of one line, at the price and tax they were billed with
curl -X POST https://api.alguna.io/invoices/inv_abc123/credit-notes \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "line_items": [ { "invoice_line_item_id": "li_xyz789", "quantity": "2" } ] }'

# 2. Apply it and refund to the original payment
curl -X POST https://api.alguna.io/credit-notes/cn_abc123/apply \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "do_refund": true, "refund_destination": "original_payment" }'

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

credit_note = requests.post(
    "https://api.alguna.io/invoices/inv_abc123/credit-notes",
    headers=headers,
    json={"line_items": [{"invoice_line_item_id": "li_xyz789", "quantity": "2"}]},
    timeout=10,
)
credit_note.raise_for_status()
credit_note_id = credit_note.json()["id"]

applied = requests.post(
    f"https://api.alguna.io/credit-notes/{credit_note_id}/apply",
    headers=headers,
    json={"do_refund": True, "refund_destination": "original_payment"},
    timeout=10,
)
applied.raise_for_status()
print(applied.json()["status"], applied.json().get("last_refund_id"))

refund_destination can also be wallet (with wallet_id) to return the money to a prepaid wallet instead of the card.

Create a refund directly

POST /refunds refunds part or all of a payment. payment_id and amount are required; reason is stored on the refund, and statement_descriptor is the text the customer sees on their statement. See Create a refund.

curl -X POST https://api.alguna.io/refunds \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_abc123",
    "amount": "75.00",
    "reason": "Duplicate charge",
    "statement_descriptor": "ACME REFUND"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/refunds",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "payment_id": "pay_abc123",
        "amount": "75.00",
        "reason": "Duplicate charge",
        "statement_descriptor": "ACME REFUND",
    },
    timeout=10,
)
response.raise_for_status()

refund = response.json()
print(refund["id"], refund["status"], refund["amount"], refund["currency"])

const refund = await alguna.refunds.create({
  payment_id: "pay_abc123",
  amount: "75.00",
  reason: "Duplicate charge",
  statement_descriptor: "ACME REFUND",
});

Find the payment to refund with GET /payments?invoice_id=… or ?customer_id=…; each payment reports amount_received and amount_refunded, so amount_received - amount_refunded is what is still refundable. See Invoicing Customers.

Partial refunds

Several partial refunds can be made against the same payment, up to the amount received:

Action	Amount	Remaining refundable
Original payment	$300.00	$300.00
First refund	$100.00	$200.00
Second refund	$75.00	$125.00
Third refund	$125.00	$0.00

Read refunds

GET /refunds filters on customer_id, payment_id, status (comma-separated), and currency; GET /refunds/{id} returns one. Each refund carries payment_id, customer_id, amount, currency, reason, failure_reason, and the provider references external_id, external_url, and processor_id.

curl "https://api.alguna.io/refunds?status=failed&limit=20&offset=0&sort=created_at:desc" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/refunds",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={"status": "failed", "limit": 20, "offset": 0, "sort": "created_at:desc"},
    timeout=10,
)
response.raise_for_status()

for refund in response.json()["data"]:
    print(refund["id"], refund["payment_id"], refund.get("failure_reason"))

const failed = await alguna.refunds.list({ status: ["failed"], limit: 20, offset: 0, sort: "created_at:desc" });

See List refunds and Get a refund.

Failed refunds

A refund fails when the provider cannot return the money — the original card is closed, the account no longer exists, or the provider reports an error. The refund stays failed with the provider’s failure_reason; it is not retried automatically. Your options are to create a new refund once the underlying problem is fixed, or to apply the credit note to a wallet so the customer can use the balance against future invoices.

In the dashboard

Payments lists every payment and, in its Refunds tab, every refund with its status. Open a payment and choose Refund to refund it directly, entering an amount and a reason.
On an invoice, Create Credit Note starts the credit-note route; when you apply the credit note to a paid invoice you pick Refund to payment method, Refund offline, or a wallet.
Refunds can be exported from the Payments page; see Data Exports.

Webhooks

Event	Fires when
`refund.updated`	A refund’s status changed
`payment.updated`	The refunded payment’s `amount_refunded` or status changed

Payloads are camelCase. See Webhooks.

Next steps

Credit Notes

The document that should accompany most refunds.

Invoicing Customers

Payments, AutoPay, and payment methods.

Surcharges

How a surcharge collected with a payment is reversed on refund.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Statuses

What happens to a paid invoice

Refund through a credit note

Create a refund directly

Partial refunds

Read refunds

Failed refunds

In the dashboard

Webhooks

Next steps

Credit Notes

Invoicing Customers

Surcharges

​Statuses

​What happens to a paid invoice

​Refund through a credit note

​Create a refund directly

​Partial refunds

​Read refunds

​Failed refunds

​In the dashboard

​Webhooks

​Next steps

Credit Notes

Invoicing Customers

Surcharges

Statuses

What happens to a paid invoice

Refund through a credit note

Create a refund directly

Partial refunds

Read refunds

Failed refunds

In the dashboard

Webhooks

Next steps