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

# Payments

> Payment status endpoints for commerce orders.

## Overview

These endpoints let you query payment status for commerce orders and invoices (useful for dashboards, reconciliation, and recovery flows).

## Authentication

Requires `x-commerce-api-key`.

## Request

Endpoints:

* `GET /api/commerce/merchant/payments/{orderId}/status`
* `POST /api/commerce/merchant/payments/bulk-status`
* `GET /api/commerce/merchant/invoices/{invoiceId}/status`

Example (single order status):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/merchant/payments/550e8400-e29b-41d4-a716-446655440111/status" \
  -H "x-commerce-api-key: ck_..."
```

## Response

Representative status response:

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440111",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "paid",
    "orderStatus": "processing",
    "customerId": "cust_123",
    "amount": 99.99,
    "paidAt": 1766320800,
    "paymentDetails": {
      "network": "base",
      "token": "USDC",
      "amount": 99.99,
      "txHash": "0xpay",
      "walletAddress": "0x0000000000000000000000000000000000000001"
    }
  }
}
```

## Errors

* `401` missing/invalid commerce API key
* `404` order/invoice not found
* `429` rate limited

## Examples

Example (bulk status):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/commerce/merchant/payments/bulk-status" \
  -H "x-commerce-api-key: ck_..." \
  -H "Content-Type: application/json" \
  -d '{"orderIds":["550e8400-e29b-41d4-a716-446655440111"]}'
```

Next: [Addresses](/api-spec/commerce/addresses)