> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-cli/checkout-sessions.md).

# Checkout Sessions

A checkout session represents a payment request. Create one when you want someone (a user, another agent, or a script) to pay a specific amount.

### Create a checkout session

```bash
ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain base
```

**Output:**

```json
{
  "session": {
    "sessionId": "cs_abc123",
    "url": "https://app.pingpay.io/checkout/cs_abc123",
    "amount": "1000000",
    "assetSymbol": "USDC",
    "assetChain": "base",
    "status": "OPEN",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "expiresAt": "2025-06-01T13:00:00.000Z"
  }
}
```

The `url` can be shared with anyone to pay via browser. The `sessionId` can be used with `ping-cli pay` for agent-to-agent payments.

#### Flags

| Flag             | Required | Description                                         |
| ---------------- | -------- | --------------------------------------------------- |
| `--amount`       | Yes      | Amount in smallest units (e.g., `1000000` = 1 USDC) |
| `--asset-symbol` | Yes      | Token symbol (`USDC`, `USDT`, `wnear`, etc.)        |
| `--asset-chain`  | Yes      | Blockchain (`base`, `near`, `eth`, etc.)            |
| `--success-url`  | No       | Redirect URL after successful payment               |
| `--cancel-url`   | No       | Redirect URL if payment is cancelled                |
| `--metadata`     | No       | JSON string of arbitrary key-value data             |

#### Amounts

Amounts are always in the **smallest unit** of the token:

| Token | Decimals | 1 token in smallest units   |
| ----- | -------- | --------------------------- |
| USDC  | 6        | `1000000`                   |
| USDT  | 6        | `1000000`                   |
| wnear | 24       | `1000000000000000000000000` |

#### Metadata

Attach arbitrary data to a checkout session:

```bash
ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain base \
  --metadata '{"orderId": "order_123", "customer": "alice"}'
```

### Get a checkout session

Retrieve a session by its ID. **No authentication required.**

```bash
ping-cli checkout get cs_abc123
```

**Output:**

```json
{
  "session": {
    "sessionId": "cs_abc123",
    "amount": "1000000",
    "assetSymbol": "USDC",
    "assetChain": "base",
    "status": "OPEN",
    "recipientAddress": "0x...",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "expiresAt": "2025-06-01T13:00:00.000Z"
  }
}
```

#### Session statuses

| Status      | Meaning                      |
| ----------- | ---------------------------- |
| `OPEN`      | Waiting for payment          |
| `PENDING`   | Payment detected, processing |
| `COMPLETED` | Payment confirmed            |
| `EXPIRED`   | Session timed out            |
| `CANCELLED` | Session was cancelled        |

### Example: Merchant agent workflow

```bash
# Create checkout
SESSION_ID=$(ping-cli checkout create \
  --amount 5000000 \
  --asset-symbol USDC \
  --asset-chain base \
  --metadata '{"product": "api-credits"}' \
  | jq -r '.session.sessionId')

echo "Send this to the payer: $SESSION_ID"

# After the payer pays, check the session
ping-cli checkout get $SESSION_ID | jq -r '.session.status'
```