# Transactions and payment attempts

> The transaction types on your account, the payment attempts behind them, and disputes, with every field the API returns.

Source: https://www.coritan.com/docs/billing/transactions/

In the dashboard:

- /dashboard/billing/transactions: https://www.coritan.com/dashboard/billing/transactions

A *transaction* is a record of money moving on your account: a payment, a refund, or credit added or used. The **Transactions** tab lists them newest first. Behind each card or PayPal payment is a *payment attempt*, one try at charging the method, and a *dispute* is a payment you asked your bank to reverse. The API lists all three.

## The Transactions tab

In the sidebar of the [dashboard](https://www.coritan.com/dashboard/billing/transactions), select **Billing**, then the **Transactions** tab.

**What**
: The transaction's description, such as `Payment for invoice INV-20260925-48213`. **See invoice** opens the invoice it belongs to.

**Type**
: `Payment`, `Refund`, `Credit added` or `Credit used`.

**Paid with**
: How the money moved: `Card`, `PayPal`, `Crypto` or `Account credit`. A payment from your credit balance shows `credit_balance`.

**Amount**
: In US dollars. Credit added has a `+` in front, and credit used a `−`.

**When**
: The date and time of the transaction.

Choose **All**, **Payments**, **Refunds** or **Credit** to show one kind. **Credit** shows credit added and credit used together, and each choice shows how many transactions it holds. Under the list, **Show** sets how many rows a page holds (10, 25, 50 or 100), and **Previous** and **Next** move between pages.

## Transaction types

| Type | Shown as | Recorded when | Description |
| --- | --- | --- | --- |
| `payment` | `Payment` | You pay an invoice with a card, PayPal or a checkout page, or Coritan charges your saved method for it. | `Payment for invoice INV-20260925-48213` |
| `credit_deduct` | `Credit used` | Coritan pays an invoice from your credit balance, in full or in part. | `Credit applied to invoice INV-20260925-48213`, or `Credit applied to first payment INV-20260925-48213` for a new order or a plan change |
| `credit_add` | `Credit added` | You add credit: with a saved method, a card, PayPal, a checkout page, automatic top-up or cryptocurrency. | `Manual top-up $25.00`, `Credit top-up $25.00 USD`, `Auto top-up $25.00` or `40.2 USDC deposit on Ethereum` |
| `refund` | `Refund` | Coritan returns a payment to the card or account it came from. | `Refund for invoice INV-20260925-48213` |

Two movements of your credit balance are not transactions, so the tab does not list them: the charges for [hourly services](/docs/billing/hourly-billing/), and the credit from a [plan change](/docs/billing/change-plan/) to a cheaper plan. `GET /billing/credit` lists them ([Billing](/docs/billing/#with-the-api)).

## Payment attempts

Each time Coritan tries to charge a card or PayPal account, it records a payment attempt with its outcome. A declined renewal charge, for example, is a `failed` attempt with the bank's reason, and the successful retry that follows is a second attempt. The dashboard does not show attempts. The API returns your last 50.

`status`
: `pending` (started), `processing` (accepted and settling, which some payment types take days to do), `requires_action` (waiting for you to confirm with your bank), `succeeded`, `failed` or `cancelled`.

`amount` and `currency`
: What was charged, in the smallest unit of the charged currency: `2500` in `USD` is $25.00.

`base_amount` and `fx_rate`
: The amount in US dollars, and the rate used to convert it into `currency`.

`error_message`, `decline_type` and `decline_code`
: Why a charge failed. `decline_type` is `soft` for a decline worth retrying, such as insufficient funds, and `hard` for one that needs a new payment method, such as an expired card. [Failed payments and suspended services](/docs/billing/failed-payments/) explains what each means for your renewals.

`invoice_id` and `payment_method_id`
: The invoice the attempt paid, and the saved method it charged. Both are `null` when they do not apply, such as a top-up with a new card.

`is_auto_charge` and `charge_schedule_id`
: Whether Coritan made the charge itself, such as a renewal retry, and the retry schedule it belongs to.

`gateway_name` and `gateway_reference`
: The payment provider account that handled the charge, and the provider's own ID for it.

`refunded_amount`
: How much of the charge was refunded, in the same unit as `amount`.

`idempotency_key`
: The `Idempotency-Key` sent with the payment, if any ([Idempotent requests](/docs/api/idempotency/)).

`created_at` and `completed_at`
: When the attempt started and when it finished.

Each attempt also carries `user_id`, `user_email`, `gateway_config_id`, `gateway_response` (the provider's answer) and `client_secret` (used to confirm a card payment in the browser).

## Disputes

A dispute, or *chargeback*, is a payment you asked your bank or PayPal to reverse. The dashboard does not show disputes. The API lists the ones on your payments and invoices.

> [!CAUTION]
> When you dispute a payment to Coritan, Coritan deletes every service on your account and closes the account, by default. Winning the dispute later does not bring deleted services back. If a charge looks wrong, [contact support](/docs/support/conversations/) before you go to your bank.

`status` and `reason`
: The payment provider's own words for the state of the dispute, such as `needs_response`, and for its cause.

`amount` and `currency`
: The amount disputed, in the smallest unit of `currency`.

`evidence_due_at`
: The date by which Coritan must answer the provider.

`payment_attempt_id`, `invoice_id` and `gateway_reference`
: The payment attempt and invoice the dispute is about, and the provider's ID for the disputed payment.

`gateway_name` and `gateway_dispute_id`
: The provider that holds the dispute, and its ID for it.

`created_at` and `updated_at`
: When Coritan recorded the dispute and last updated it.

## With the API

### List transactions

[`GET /billing/transactions`](/docs/api/reference/client/billing/#op-get-api-v1-billing-transactions) lists your transactions, newest first. It takes `page` (from 1), `limit` (default 50, at most 200) and `type_filter`: `payment`, `refund`, `credit_add`, `credit_deduct`, or `credit` for both credit types. Add `with_total=true` to get the page with its counts:

```bash
curl "https://api.coritan.com/api/v1/billing/transactions?type_filter=payment&limit=25&with_total=true" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "items": [
    {
      "id": 7310,
      "user_id": 1482,
      "invoice_id": 5120,
      "amount": 13.47,
      "currency": "USD",
      "transaction_type": "payment",
      "gateway": "stripe",
      "gateway_reference": "pi_3Qexample",
      "description": "Payment for invoice INV-20260925-48213",
      "created_at": "2026-09-25T10:12:44"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25,
  "counts": {"all": 7, "credit": 6, "payment": 1, "refund": 0, "credit_add": 4, "credit_deduct": 2}
}
```

`total` is how many transactions match `type_filter`, and `counts` holds the number of each type whatever the filter. Without `with_total`, the answer is the list of transactions alone. `amount` is in US dollars and is negative for a refund. `gateway` is `credit_balance` for credit used, and `null` or a provider name otherwise. A `type_filter` outside the list answers `422`.

### List payment attempts

[`GET /payments/attempts`](/docs/api/reference/client/payments/#op-get-api-v1-payments-attempts) returns your last 50 payment attempts, newest first. It takes no parameters.

```bash
curl https://api.coritan.com/api/v1/payments/attempts \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

Each item has the fields under [Payment attempts](#payment-attempts).

### List disputes

[`GET /payments/disputes`](/docs/api/reference/client/payments/#op-get-api-v1-payments-disputes) lists your disputes, newest first. It takes `limit` (default 50, at most 100) and `offset`:

```bash
curl "https://api.coritan.com/api/v1/payments/disputes?limit=20" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "disputes": [],
  "limit": 20,
  "offset": 0
}
```

Each item in `disputes` has the fields under [Disputes](#disputes) and its `id`.

## API

- `GET /api/v1/billing/transactions`: As listinvoices: newest first, ties by id, withtotal for a TransactionPage (https://www.coritan.com/docs/api/reference/client/billing/#op-get-api-v1-billing-transactions)
- `GET /api/v1/payments/attempts`: List payment attempts (https://www.coritan.com/docs/api/reference/client/payments/#op-get-api-v1-payments-attempts)
- `GET /api/v1/payments/disputes`: List disputes tied to the caller's payment attempts / invoices only (https://www.coritan.com/docs/api/reference/client/payments/#op-get-api-v1-payments-disputes)