# `PaperTiger.Resources.Topup`
[🔗](https://github.com/EnaiaInc/paper_tiger/blob/v1.2.2/lib/paper_tiger/resources/topup.ex#L1)

Handles Topup resource endpoints.

## Endpoints

- POST   /v1/topups      - Create topup
- GET    /v1/topups/:id  - Retrieve topup
- POST   /v1/topups/:id  - Update topup
- GET    /v1/topups      - List topups

Note: Topups cannot be deleted (only canceled).

## Topup Object

    %{
      id: "tu_...",
      object: "topup",
      created: 1234567890,
      amount: 2000,
      currency: "usd",
      status: "pending" | "succeeded" | "failed" | "canceled" | "reversed",
      description: "Account top-up",
      metadata: %{},
      # ... other fields
    }

# `create`

```elixir
@spec create(Plug.Conn.t()) :: Plug.Conn.t()
```

Creates a new topup.

## Required Parameters

- amount - Amount in cents (e.g., 2000 for $20.00)
- currency - Three-letter ISO currency code (e.g., "usd")
- description - Topup description

## Optional Parameters

- metadata - Key-value metadata

# `list`

```elixir
@spec list(Plug.Conn.t()) :: Plug.Conn.t()
```

Lists all topups with pagination.

## Parameters

- limit - Number of items (default: 10, max: 100)
- starting_after - Cursor for pagination
- ending_before - Reverse cursor
- status - Filter by status

# `retrieve`

```elixir
@spec retrieve(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Retrieves a topup by ID.

# `update`

```elixir
@spec update(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Updates a topup.

Note: Topups can only have limited fields updated.

## Updatable Fields

- description
- metadata

---

*Consult [api-reference.md](api-reference.md) for complete listing*