Skip to main content
GET
/
v1
/
invoices
/
{id}
Get invoice
curl --request GET \
  --url https://api.gwop.io/v1/invoices/{id}
{
  "id": "904e9f44-a5a3-4e07-94c9-9c425d6bbe64",
  "status": "OPEN",
  "amount_usdc": 1000000,
  "currency": "USDC",
  "expires_at": "2026-02-02T12:00:00.000Z",
  "created_at": "2026-02-02T12:00:00.000Z",
  "merchant": {
    "name": "<string>",
    "verified": true
  },
  "consumption": {
    "type": "redeliverable",
    "replay_safe": true,
    "guidance": "Safe to retry content delivery with X-Gwop-Invoice-Id header.",
    "max_replays": 123,
    "replay_window_expires_at": "2026-02-02T12:00:00.000Z"
  },
  "payment_address": "9BXLEjmgaB2EWQcjSvrQWcDRVhqqdAXwZkiuWmLEY17e",
  "solana_pay_url": "solana:9BXLEjmgaB2EWQcjSvrQWcDRVhqqdAXwZkiuWmLEY17e?amount=0.1&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&reference=5YdwM6AuQH5vdwqUZtJvM4z7bW2pnTP3XxHhJvGrHq4n",
  "gwop_pay_url": "https://pay.gwop.io/pay/f6a03b6f-29b0-4477-9cc5-644d5678f5d4",
  "reference_pubkey": "5YdwM6AuQH5vdwqUZtJvM4z7bW2pnTP3XxHhJvGrHq4n",
  "verify_payment_endpoint": "/v1/invoices/f6a03b6f-29b0-4477-9cc5-644d5678f5d4/verify-payment",
  "x402_endpoint": "/v1/invoices/f6a03b6f-29b0-4477-9cc5-644d5678f5d4/x402",
  "payment_options": [
    {
      "id": "<string>",
      "method": "gwop_wallet",
      "amount_usdc": 1000000,
      "currency": "USDC",
      "payment_chain": "solana",
      "payment_chain_caip2": "eip155:8453",
      "recipient_address": "<string>",
      "endpoint": "<string>",
      "url": "<string>",
      "asset": {
        "symbol": "USDC",
        "decimals": 6,
        "mint": "<string>",
        "contract": "<string>"
      }
    }
  ],
  "preferred_payment_method": "gwop_wallet",
  "description": "<string>",
  "metadata": {},
  "paid_at": "2026-02-02T12:00:00.000Z",
  "paid_amount": 1000000,
  "payment_chain": "solana",
  "payment_chain_caip2": "solana:mainnet",
  "tx_signature": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
  "tx_url": "https://solscan.io/tx/5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
  "agent_guidance": {
    "message": "<string>",
    "persist": {
      "action": "create",
      "path": "~/.config/gwop/orders/my-store/904e9f44-a5a3-4e07-94c9-9c425d6bbe64.json",
      "required_fields": [
        "invoice_id",
        "delivery_token",
        "pay_url",
        "payment_details_url",
        "delivery_url"
      ],
      "persist_full_response": true
    },
    "next_step": "<string>"
  }
}

Path Parameters

​
id
string<uuid>
required

Invoice ID (UUID) UUID v4 identifier

Example:

"904e9f44-a5a3-4e07-94c9-9c425d6bbe64"

Response

Invoice details

​
id
string<uuid>
required

UUID v4 identifier

Example:

"904e9f44-a5a3-4e07-94c9-9c425d6bbe64"

​
status
enum<string>
required

Invoice lifecycle status.

OPEN ──[pay]──> PAYING ──[confirm]──> PAID
 │                ▲
 │                │
 └────[fails]─────┘ (rolls back to OPEN)

OPEN ──[cancel]──> CANCELED
OPEN ──[expires]──> EXPIRED
Available options:
OPEN,
PAYING,
PAID,
EXPIRED,
CANCELED
​
amount_usdc
integer<int64>
required

Amount in USDC minor units (6 decimals).

Human ReadableAPI Value
$1.001000000
$0.0110000
$100.00100000000
$10,000.00 (max)10000000000
Required range: 1 <= x <= 10000000000
Example:

1000000

​
currency
enum<string>
required

Currency code. Currently only USDC is supported.

Available options:
USDC
Example:

"USDC"

​
expires_at
string<date-time>
required

ISO 8601 timestamp in UTC

Example:

"2026-02-02T12:00:00.000Z"

​
created_at
string<date-time>
required

ISO 8601 timestamp in UTC

Example:

"2026-02-02T12:00:00.000Z"

​
merchant
object
required
​
consumption
object
required
​
payment_address
string

Merchant's Solana wallet address for direct USDC transfers. Only present when status is OPEN.

External agents can pay by sending USDC to this address and calling POST /v1/invoices/{id}/verify-payment.

Example:

"9BXLEjmgaB2EWQcjSvrQWcDRVhqqdAXwZkiuWmLEY17e"

​
solana_pay_url
string<uri>

Solana Pay URL for wallet scanning. Only present when status is OPEN.

Compatible with Phantom, Solflare, and other Solana Pay wallets. Encode this as a QR code for mobile wallet scanning.

Format: solana:<address>?amount=<amount>&spl-token=<usdc_mint>&reference=<reference_pubkey>

Example:

"solana:9BXLEjmgaB2EWQcjSvrQWcDRVhqqdAXwZkiuWmLEY17e?amount=0.1&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&reference=5YdwM6AuQH5vdwqUZtJvM4z7bW2pnTP3XxHhJvGrHq4n"

​
gwop_pay_url
string<uri>

Gwop Pay URL for human-friendly payment and invoice viewing. Safe to share and works for OPEN and PAID invoices.

Example:

"https://pay.gwop.io/pay/f6a03b6f-29b0-4477-9cc5-644d5678f5d4"

​
reference_pubkey
string

Solana Pay reference public key (base58). Use this to correlate on-chain payments to the invoice.

Example:

"5YdwM6AuQH5vdwqUZtJvM4z7bW2pnTP3XxHhJvGrHq4n"

​
verify_payment_endpoint
string

Endpoint to verify external payment

Example:

"/v1/invoices/f6a03b6f-29b0-4477-9cc5-644d5678f5d4/verify-payment"

​
x402_endpoint
string

Endpoint to request x402 requirements and submit external payment proof

Example:

"/v1/invoices/f6a03b6f-29b0-4477-9cc5-644d5678f5d4/x402"

​
payment_options
object[]

Chain-balanced payment options for this invoice (OPEN only).

​
preferred_payment_method
enum<string>

Suggested first payment path for agents.

Available options:
gwop_wallet,
x402,
gwop_pay_link
​
description
string

Only if metadata_public was true

​
metadata
object

Only if metadata_public was true

​
paid_at
string<date-time>

ISO 8601 timestamp in UTC

Example:

"2026-02-02T12:00:00.000Z"

​
paid_amount
integer<int64>

Amount in USDC minor units (6 decimals).

Human ReadableAPI Value
$1.001000000
$0.0110000
$100.00100000000
$10,000.00 (max)10000000000
Required range: 1 <= x <= 10000000000
Example:

1000000

​
payment_chain
enum<string>

Chain where payment was settled.

Available options:
solana,
base
​
payment_chain_caip2
string

CAIP-2 identifier for the payment chain.

Example:

"solana:mainnet"

​
tx_signature
string

Base58-encoded Solana transaction signature

Pattern: ^[1-9A-HJ-NP-Za-km-z]{87,88}$
Example:

"5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW"

​
tx_url
string<uri>

Solscan explorer link

Example:

"https://solscan.io/tx/5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW"

​
agent_guidance
object

Includes persistence guidance for payment and storefront delivery flows.