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

# Orders & Payments

> Track transactions and manage your payment lifecycle

## Overview

Every purchase in Waffo Pancake creates an **order** and an associated **payment** record. Orders represent the customer's intent to buy, while payments track the actual money movement.

***

## Order Statuses

Orders have different status sets depending on the product type.

### One-Time Orders

| Status     | Description                          |
| ---------- | ------------------------------------ |
| `pending`  | Order created, awaiting payment      |
| `paid`     | Payment succeeded, order fulfilled   |
| `canceled` | Order was canceled before completion |

### Subscription Orders

| Status      | Description                                               |
| ----------- | --------------------------------------------------------- |
| `pending`   | Subscription created, awaiting first payment              |
| `active`    | Subscription is live and billing normally                 |
| `trialing`  | Customer is in a free trial period                        |
| `past_due`  | Payment failed, retrying                                  |
| `canceling` | Cancellation requested, active until period end           |
| `canceled`  | Subscription canceled (access continues until period end) |
| `expired`   | Subscription expired                                      |
| `closed`    | Never activated — payment timed out                       |

***

## Payment Statuses

<CardGroup cols={3}>
  <Card title="Pending" icon="clock" color="#f59e0b">
    Payment initiated, awaiting processing.
  </Card>

  <Card title="Processing" icon="spinner" color="#3b82f6">
    Payment is being processed.
  </Card>

  <Card title="Succeeded" icon="check" color="#22c55e">
    Payment completed successfully.
  </Card>

  <Card title="Failed" icon="xmark" color="#ef4444">
    Payment failed during processing.
  </Card>

  <Card title="Canceled" icon="ban" color="#6b7280">
    Payment was canceled (timeout, merchant action, or buyer cancellation before processing).
  </Card>

  <Card title="Refunded" icon="rotate-left" color="#6366f1">
    Full refund has been processed.
  </Card>

  <Card title="Partially Refunded" icon="circle-half-stroke" color="#8b5cf6">
    A partial refund has been processed.
  </Card>
</CardGroup>

<Note>
  `processing` may appear in the Dashboard UI but is not returned by the API or GraphQL. Payment statuses from the API are: `pending`, `succeeded`, `failed`, `canceled`.
</Note>

<Note>
  Refund status is tracked separately via the `refundStatus` field on Payment (`none` / `pending` / `refunded` / `failed`), not as a payment status value.
</Note>

***

## Payment List

View all payments in a table with the following columns:

| Column         | Description                               |
| -------------- | ----------------------------------------- |
| Date           | Transaction timestamp                     |
| Amount         | Payment amount as a display format string |
| Tax Amount     | Tax collected on the transaction          |
| Status         | Current payment status                    |
| Payment Method | `card`, `bank_transfer`, or `wallet`      |
| Customer       | Customer email address                    |
| Currency       | ISO 4217 currency code                    |

### Filtering

| Filter     | Options                                                                          |
| ---------- | -------------------------------------------------------------------------------- |
| Status     | `pending`, `processing`, `succeeded`, `failed`, `refunded`, `partially_refunded` |
| Date Range | Custom start and end dates                                                       |

***

## Payment Details

Click any payment to view its full record.

### Transaction Info

| Field      | Description                                  |
| ---------- | -------------------------------------------- |
| Payment ID | UUID v4 identifier                           |
| Order ID   | Associated order                             |
| Store ID   | Store that received the payment              |
| Amount     | Gross payment amount (display format string) |
| Currency   | ISO 4217 currency code                       |
| Status     | Current payment status                       |
| Created At | ISO 8601 timestamp                           |
| Updated At | ISO 8601 timestamp                           |

### Amount Details

| Field                | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `amount`             | Total charged amount                                  |
| `taxAmount`          | Tax portion of the amount                             |
| `settlementCurrency` | Currency used for settlement                          |
| `settlementAmount`   | Amount in settlement currency (display format string) |
| `refundedAmount`     | Total amount refunded so far                          |

### Billing Detail

| Field          | Description                         |
| -------------- | ----------------------------------- |
| `country`      | Customer's billing country          |
| `state`        | Billing state or region             |
| `postcode`     | Billing postal code                 |
| `isBusiness`   | Whether this is a business purchase |
| `businessName` | Business name (if applicable)       |
| `taxId`        | Tax ID (if applicable)              |

### Payment Method

Payments record which method was used:

| Method            | Value           |
| ----------------- | --------------- |
| Credit/Debit Card | `card`          |
| Bank Transfer     | `bank_transfer` |
| Digital Wallet    | `wallet`        |

Additional method-specific details may be available in the `paymentMethodDetails` field. The structure of this field varies by payment method.

***

## Supported Payment Methods

<CardGroup cols={3}>
  <Card title="Card" icon="credit-card">
    Credit and debit card payments.
  </Card>

  <Card title="Bank Transfer" icon="building-columns">
    Direct bank-to-bank transfers.
  </Card>

  <Card title="Wallet" icon="wallet">
    Digital wallet payments (Apple Pay, Google Pay, etc.).
  </Card>
</CardGroup>

***

## Refunds

Refund requests are handled through a separate ticket-based workflow. Buyers submit a refund ticket specifying the payment and reason, and merchants review and approve or reject the request.

<Note>
  For full details on the refund process, statuses, and policies, see the [Refunds](/customers/refunds) page.
</Note>

**Key rules:**

* One-time product refunds must be requested within **14 days** of payment
* Subscription cancellations take effect at the end of the current billing period
* Refund tickets track their own status: `pending`, `approved`, `rejected`, `processing`, `succeeded`, `failed`

***

## API Reference

### Creating Orders

Orders are created through a two-step checkout session flow:

**Step 1: Create a checkout session** (API Key or Store Slug auth)

<CodeGroup>
  ```bash One-Time Product theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "storeId": "store-uuid",
      "productId": "product-uuid",
      "productType": "onetime",
      "currency": "USD"
    }'
  ```

  ```bash Subscription Product theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "storeId": "store-uuid",
      "productId": "product-uuid",
      "productType": "subscription",
      "currency": "USD"
    }'
  ```
</CodeGroup>

This returns a `sessionId`, `checkoutUrl`, and `expiresAt`. The session locks the product version and price snapshot for 7 days.

**Step 2: Create the order** (API Key auth)

<CodeGroup>
  ```bash One-Time Order theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/onetime-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```

  ```bash Subscription Order theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/subscription-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```
</CodeGroup>

Both endpoints return a `checkoutUrl` that the buyer should be redirected to for payment.

### Querying Payments

Use the GraphQL endpoint to query payment records:

```graphql theme={"system"}
query {
  payments(storeId: "store-uuid", limit: 20) {
    id
    orderId
    amount
    currency
    status
    paymentMethod
    amountDetails {
      amount
      taxAmount
      settlementCurrency
      settlementAmount
      refundedAmount
    }
    billingDetail {
      country
      state
      postcode
      isBusiness
      businessName
      taxId
    }
    createdAt
  }
}
```

<Tip>
  All amounts are display format strings. For example, `"29.00"` in USD means \$29.00. For zero-decimal currencies like JPY, `"4500"` means 4500 yen.
</Tip>