> 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/payments.md).

# Payments

### Pay a checkout (high-level)

The simplest way to pay a checkout session. One command: prepares the payment, sends USDC from your connected wallet, and returns the transaction hash.

```bash
ping-cli pay --session-id cs_abc123
```

**Output:**

```json
{
  "success": true,
  "paymentId": "pay_xyz789",
  "depositAddress": "0xdeposit...",
  "txHash": "0xabc123...",
  "explorer": "https://basescan.org/tx/0xabc123...",
  "amount": "1000000",
  "asset": "USDC",
  "chain": "base"
}
```

> **Requires** a connected wallet (`wallet create` or `wallet connect`).
>
> **Currently supports USDC on Base only.**

#### Flags

| Flag             | Required | Default | Description                |
| ---------------- | -------- | ------- | -------------------------- |
| `--session-id`   | Yes      | —       | Checkout session ID to pay |
| `--asset-symbol` | No       | `USDC`  | Asset to pay with          |
| `--asset-chain`  | No       | `base`  | Chain to pay on            |

***

### Low-level payment commands

For more control over the payment lifecycle, use these commands individually.

#### Prepare a payment

Get a deposit address and quote before sending funds. Useful when you want to review the details or handle the transfer yourself.

```bash
ping-cli payment prepare \
  --session-id cs_abc123 \
  --payer-address 0xYourWallet \
  --asset-symbol USDC \
  --asset-chain base \
  --amount 1000000
```

**Output:**

```json
{
  "paymentId": "pay_xyz789",
  "depositAddress": "0xdeposit...",
  "quote": {
    "amountIn": "1000000",
    "exchangeRate": "1.0"
  }
}
```

**Flags**

| Flag                | Required | Description               |
| ------------------- | -------- | ------------------------- |
| `--session-id`      | Yes      | Checkout session ID       |
| `--payer-address`   | Yes      | Your wallet address       |
| `--asset-symbol`    | Yes      | Asset to pay with         |
| `--asset-chain`     | Yes      | Chain to pay on           |
| `--amount`          | Yes      | Amount in smallest units  |
| `--idempotency-key` | No       | Auto-generated if omitted |

#### Get a payment

Retrieve payment details by ID:

```bash
ping-cli payment get pay_xyz789
```

**Output:**

```json
{
  "payment": {
    "id": "pay_xyz789",
    "sessionId": "cs_abc123",
    "amount": "1000000",
    "status": "SUCCESS",
    "depositAddress": "0xdeposit...",
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
}
```

#### List payments

List payments with optional filtering:

```bash
# List all payments
ping-cli payment list

# Filter by status
ping-cli payment list --status SUCCESS

# Paginate
ping-cli payment list --limit 10 --offset 20
```

**Flags**

| Flag       | Default | Description                                                     |
| ---------- | ------- | --------------------------------------------------------------- |
| `--limit`  | `50`    | Max results (1-100)                                             |
| `--offset` | `0`     | Pagination offset                                               |
| `--status` | —       | Filter: `CREATED`, `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED` |

#### Check payment status

Check the on-chain status of a payment by its deposit address:

```bash
ping-cli payment status 0xdeposit...
```

**Output:**

```json
{
  "status": "SUCCESS",
  "txId": "0xtx...",
  "reason": null,
  "updatedAt": "2025-06-01T12:05:00.000Z"
}
```

#### Wait for payment completion

Block until a payment reaches a terminal state (`SUCCESS`, `FAILED`, or `REFUNDED`). Polls every 2 seconds.

```bash
ping-cli payment wait pay_xyz789
```

Set a custom timeout (default is 300 seconds):

```bash
ping-cli payment wait pay_xyz789 --timeout 600
```

**Output (on completion):**

```json
{
  "status": "SUCCESS",
  "txId": "0xtx...",
  "reason": null,
  "updatedAt": "2025-06-01T12:05:00.000Z"
}
```

This command is essential for agent workflows where the agent needs to confirm payment before proceeding.

**Flags**

| Flag        | Default | Description        |
| ----------- | ------- | ------------------ |
| `--timeout` | `300`   | Timeout in seconds |

***

### Payment statuses

| Status       | Meaning                               |
| ------------ | ------------------------------------- |
| `CREATED`    | Payment prepared, waiting for deposit |
| `PENDING`    | Deposit detected                      |
| `PROCESSING` | Settlement in progress                |
| `SUCCESS`    | Payment confirmed                     |
| `FAILED`     | Payment failed                        |
| `REFUNDED`   | Payment was refunded                  |

***

### Example: Full agent payment flow

```bash
# 1. Prepare (get deposit address)
PAYMENT=$(ping-cli payment prepare \
  --session-id cs_abc123 \
  --payer-address 0xMyWallet \
  --asset-symbol USDC \
  --asset-chain base \
  --amount 1000000)

PAYMENT_ID=$(echo $PAYMENT | jq -r '.paymentId')
DEPOSIT=$(echo $PAYMENT | jq -r '.depositAddress')

# 2. Send funds to the deposit address (via your own wallet tooling)
# ...

# 3. Wait for confirmation
ping-cli payment wait $PAYMENT_ID --timeout 600
```

Or just use `ping-cli pay` to do it all in one step.