# Transactions

Read checkout payment attempts, look up a payment by your reference, and list a user's successful sales.

Read your organization's checkout attempts. Use these to reconcile payments, look up a specific attempt by your own reference, or list a buyer's completed purchases. All endpoints are scoped to your API-key organization and paginate with `limit` (1–100, default 50) and `offset` (default 0).

## The transaction object

```json
{
  "id": "310ace43-4c69-4fd2-acd8-94645dbe1938",
  "transactionReference": "txn_1048",
  "userId": "user_42",
  "buyerEmail": "ana.silva@example.com",
  "product": {
    "id": "6a713a92-350a-4cc6-a996-1e55e97d3a36",
    "externalProductId": "curso-pro",
    "slug": "c-8f41a2d9",
    "name": "Curso Pro"
  },
  "amount": "49.90",
  "amountReceived": "49.90",
  "pricing": {
    "originalAmount": "62.38",
    "discountPercent": "20.00",
    "discountAmount": "12.48",
    "finalAmount": "49.90",
    "currency": "BRL"
  },
  "currency": "BRL",
  "paymentCurrency": "BRL",
  "settlementCurrency": "USDC",
  "status": "paid",
  "paymentMethod": "bank",
  "paymentRail": "pix",
  "chain": null,
  "txSignature": null,
  "expiresAt": "2026-07-22T12:30:00.000Z",
  "createdAt": "2026-07-22T12:00:00.000Z",
  "updatedAt": "2026-07-22T12:04:10.000Z"
}
```

- `status` is `created`, `pending`, `underpaid`, `paid`, `expired`, or `failed`. `paid` covers the internal paid, swept, and PIX completed states; an unrecognized legacy value is projected as `unknown`.
- PIX uses `paymentMethod: "bank"`, `paymentRail: "pix"`, BRL amounts, and null `chain`/`txSignature`. Crypto uses `paymentMethod: "crypto"`, an on-chain `chain`/`txSignature`, and a null `paymentRail`.
- `transactionReference` is `null` when the hosted URL had no `txn_id`; `userId` is `null` when no `userID` was supplied. Product fields can be `null` for legacy or detached charges.
- `pricing` records the original amount and one-off percentage discount for an API-created session. `amount` is always the final payable total. The field is `null` for charges without session pricing metadata.

## List transactions

```http
GET /v1/checkout/transactions
x-api-key: dlfy_live_...
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `status` | `all` | `all`, `created`, `pending`, `underpaid`, `paid`, `expired`, or `failed`. `paid` includes swept and PIX completed. |
| `transactionReference` | — | Exact merchant `txn_id`. |
| `userId` | — | Exact merchant `userID`. |
| `buyerEmail` | — | Exact buyer email; matching is case-insensitive. |
| `limit` | `50` | 1–100. |
| `offset` | `0` | Zero or greater. |

Returns `{ "transactions": [ ... ], "pagination": { "limit", "offset", "hasMore" } }`, newest first.
Multiple filters can be combined and are always scoped to your API-key organization.

For example:

```http
GET /v1/checkout/transactions?userId=user_42&buyerEmail=ana.silva%40example.com
x-api-key: dlfy_live_...
```

## Get a payment by your reference

```http
GET /v1/checkout/transactions/:transactionReference
x-api-key: dlfy_live_...
```

Looks up an exact, URL-encoded merchant `txn_id`. If the reference has multiple attempts, a successful attempt wins; otherwise the newest is returned. `attemptCount` reports how many attempts matched.

```json
{
  "reference": "txn_1048",
  "status": "paid",
  "attemptCount": 1,
  "transaction": { }
}
```

Unknown references return `404 checkout_transaction_not_found`.

## List a user's sales

```http
GET /v1/checkout/users/:userId/sales
x-api-key: dlfy_live_...
```

Lists **successful** sales for an exact, URL-encoded merchant `userID`, newest first. Only paid charges are included (all projected as `status: "paid"`).

```json
{
  "userId": "user_42",
  "sales": [ { } ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}
```

Each entry uses the transaction object above.