> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fungies.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment

> The Payment object represents a financial transaction in your Fungies store.

A Payment object represents a single financial transaction - either a one-time purchase or a recurring subscription charge. Payments track the monetary flow, including the amount, fees, tax, and processing status.

Each payment is associated with an [Order](/core-resources/order) and optionally with a [User](/core-resources/user) and [Subscription](/core-resources/subscription). Payments contain detailed information about charges, including payment method details and invoice data when applicable.

## Endpoints

| Method | Endpoint                   | Description              |
| ------ | -------------------------- | ------------------------ |
| `GET`  | `/v0/payments/list`        | List and filter payments |
| `GET`  | `/v0/payments/{paymentId}` | Retrieve a payment by ID |

## The Payment object

<ResponseField name="object" type="string">
  Object type identifier. Always `"payment"` for Payment objects.
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for this payment.
</ResponseField>

<ResponseField name="number" type="string" required>
  Human-readable payment number (e.g., `#ABC123DEF456`). Used for reference in invoices and support.
</ResponseField>

<ResponseField name="type" type="string" required>
  Type of payment. Possible values: `one_time`, `subscription_initial`, `subscription_update`, `subscription_interval`, `subscription_extra`, `claim_free`
</ResponseField>

<ResponseField name="status" type="string" required>
  Current payment status. Possible values: `PENDING`, `PAID`, `FAILED`, `UNPAID`, `CANCELLED`, `REFUNDED`, `PARTIALLY_REFUNDED`, `EXPIRED`
</ResponseField>

<ResponseField name="value" type="integer">
  Payment amount in the smallest currency unit (e.g., cents for USD). Includes tax but excludes fees. Defaults to `0`.
</ResponseField>

<ResponseField name="tax" type="integer">
  Tax amount in the smallest currency unit. Included in the total value. Defaults to `0`.
</ResponseField>

<ResponseField name="fee" type="integer">
  Processing fee in the smallest currency unit. This is deducted from your payout. Defaults to `0`.
</ResponseField>

<ResponseField name="currency" type="string | null">
  Three-letter ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`).
</ResponseField>

<ResponseField name="currencyDecimals" type="integer | null">
  Number of decimal places for this currency (e.g., `2` for USD, `0` for JPY).
</ResponseField>

<ResponseField name="createdAt" type="integer">
  Unix timestamp (milliseconds) when the payment was created.
</ResponseField>

<ResponseField name="userId" type="string | null">
  UUID of the [User](/core-resources/user) who made this payment.
</ResponseField>

<ResponseField name="user" type="User | null">
  Expanded [User object](/core-resources/user) with basic information about the payer.

  <Expandable title="user properties">
    <ResponseField name="object" type="string">
      Always `"user"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this user.
    </ResponseField>

    <ResponseField name="username" type="string | null">
      Username of the user.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="orderId" type="string | null">
  UUID of the associated [Order](/core-resources/order). For subscription payments, this links to the initial order.
</ResponseField>

<ResponseField name="orderNumber" type="string | null">
  Human-readable order number of the associated order.
</ResponseField>

<ResponseField name="order" type="Order | null">
  Expanded [Order object](/core-resources/order) with basic information.

  <Expandable title="order properties">
    <ResponseField name="object" type="string">
      Always `"order"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this order.
    </ResponseField>

    <ResponseField name="number" type="string" required>
      Human-readable order number.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current order status.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="subscriptionId" type="string | null">
  [Subscription](/core-resources/subscription) identifier if this is a subscription-related payment.
</ResponseField>

<ResponseField name="subscription" type="Subscription | null">
  Expanded [Subscription object](/core-resources/subscription) with status and ID.

  <Expandable title="subscription properties">
    <ResponseField name="object" type="string">
      Always `"subscription"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Subscription identifier.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Subscription status: `active`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing`, `paused`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="discount" type="Discount | null">
  Applied [Discount object](/core-resources/discount) if a discount code or sale was used.

  <Expandable title="discount properties">
    <ResponseField name="object" type="string">
      Always `"discount"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this discount.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Discount type: `code` or `sale`.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Display name of the discount.
    </ResponseField>

    <ResponseField name="amount" type="number" required>
      Discount amount (fixed value or percentage).
    </ResponseField>

    <ResponseField name="amountType" type="string" required>
      Whether amount is `fixed` or `percentage`.
    </ResponseField>

    <ResponseField name="discountCode" type="string | null">
      The coupon code if this is a code-type discount.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="invoiceNumber" type="string | null">
  Invoice number for completed payments. Only available for `PAID`, `REFUNDED`, or `PARTIALLY_REFUNDED` statuses.
</ResponseField>

<ResponseField name="invoiceUrl" type="string | null">
  URL to download the invoice PDF. Only available for completed payments with generated invoices.
</ResponseField>

<ResponseField name="charges" type="array | null">
  Array of charge attempts for this payment.

  <Expandable title="charge properties">
    <ResponseField name="object" type="string">
      Always `"charge"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this charge.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Charge status: `succeeded`, `pending`, `failed`
    </ResponseField>

    <ResponseField name="createdAt" type="number | null">
      Unix timestamp (milliseconds) when the charge was created.
    </ResponseField>

    <ResponseField name="ipAddress" type="string | null">
      IP address of the customer at time of charge.
    </ResponseField>

    <ResponseField name="paymentMethod" type="object | null">
      Payment method details including `type`, `brand`, `last4`, and `card`.

      <Expandable>
        <ResponseField name="type" type="string">
          Payment method type (e.g., card, paypal, bank\_transfer, klarna, affirm).
        </ResponseField>

        <ResponseField name="brand" type="string | null">
          Card brand if payment method is a card (visa, mastercard, amex, discover, diners, jcb, unionpay).
        </ResponseField>

        <ResponseField name="last4" type="string | null">
          Last 4 digits of the card or account number.
        </ResponseField>

        <ResponseField name="card" type="object">
          Card-specific payment details. Present when the payment method type is `card`.

          <Expandable>
            <ResponseField name="brand" type="string | null">
              Card brand (visa, mastercard, amex, discover, diners, jcb, unionpay).
            </ResponseField>

            <ResponseField name="last4" type="string | null">
              Last 4 digits of the card number.
            </ResponseField>

            <ResponseField name="country" type="string | null">
              Two-letter ISO country code of the card issuer.
            </ResponseField>

            <ResponseField name="network" type="string | null">
              Card network (e.g., visa, mastercard).
            </ResponseField>

            <ResponseField name="wallet" type="object | null">
              Digital wallet details, if the card payment was made via a wallet (e.g., Apple Pay, Google Pay). Null when no wallet was used.

              <Expandable>
                <ResponseField name="type" type="string">
                  The type of digital wallet: `amex_express_checkout`, `apple_pay`, `google_pay`, `link`, `masterpass`, `samsung_pay`, or `visa_checkout`.
                </ResponseField>

                <ResponseField name="dynamicLast4" type="string | null">
                  The last four digits of the device account number. May differ from the physical card's last4.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "payment": {
      "object": "payment",
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "number": "#PAY123DEF456",
      "type": "one_time",
      "status": "PAID",
      "value": 2999,
      "tax": 500,
      "fee": 87,
      "currency": "USD",
      "currencyDecimals": 2,
      "createdAt": 1705590000000,
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {
        "object": "user",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "johndoe"
      },
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "#ABC123DEF456",
      "order": {
        "object": "order",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "number": "#ABC123DEF456",
        "status": "PAID"
      },
      "subscriptionId": null,
      "subscription": null,
      "discount": null,
      "invoiceNumber": "INV-2024-001234",
      "invoiceUrl": "https://api.fungies.io/invoice/INV-2024-001234",
      "charges": [
        {
          "object": "charge",
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "status": "succeeded",
          "createdAt": 1705590000000,
          "ipAddress": "192.168.1.100",
          "paymentMethod": {
            "type": "card",
            "brand": "visa",
            "last4": "4242",
            "card": {
              "brand": "visa",
              "last4": "4242",
              "country": "US",
              "network": "visa",
              "wallet": {
                "type": "apple_pay",
                "dynamicLast4": "7279"
              }
            }
          }
        }
      ]
    }
  }
}
```

***

## Related resources

<CardGroup cols={2}>
  <Card title="Orders" icon="receipt" href="/core-resources/order">
    Orders associated with payments
  </Card>

  <Card title="Users" icon="user" href="/core-resources/user">
    Customers who made payments
  </Card>

  <Card title="Subscriptions" icon="rotate" href="/core-resources/subscription">
    Recurring subscription payments
  </Card>

  <Card title="Discounts" icon="percent" href="/core-resources/discount">
    Discounts applied to payments
  </Card>
</CardGroup>