Get Invoice

The public checkout session with x402 payment rails and status

Get Invoice

The public checkout session with x402 payment rails and status

Get an invoice

Fetch the public checkout session by publicInvoiceId. This endpoint requires no authentication — it is the view agents use to discover available x402 payment methods and settle the checkout.

1 import { Gwop } from "@gwop/sdk";
2 
3 const gwop = new Gwop({
4   merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5 });
6 
7 const { result: invoice } = await gwop.invoices.get({
8   id: "inv_af95ad98fadb4599aab6373ac812842e",
9 });
10 
11 console.log(invoice.status);                    // "OPEN"
12 console.log(invoice.amount.display);            // "1.025 USDC"
13 console.log(invoice.paymentMethods);            // [{id: "x402-base", ...}, ...]
14 console.log(invoice.merchant.name);             // "agentrouter"
15 console.log(invoice.statusCheck.url);           // Polling URL

Response (OPEN invoice)

1 {
2   "schemaVersion": "gwop.invoice.v4",
3   "id": "inv_af95ad98fadb4599aab6373ac812842e",
4   "status": "OPEN",
5   "amount": {
6     "value": 1025000,
7     "display": "1.025 USDC",
8     "currency": "USDC",
9     "decimals": 6
10   },
11   "pricing": {
12     "baseAmount": 1000000,
13     "gwopFee": 25000,
14     "total": 1025000
15   },
16   "expiresAt": "2026-04-08T22:55:04.088Z",
17   "createdAt": "2026-04-08T22:40:04.122Z",
18   "merchant": {
19     "name": "agentrouter",
20     "verified": true
21   },
22   "statusCheck": {
23     "url": "https://agents.gwop.io/v1/invoices/inv_af95ad98fadb4599aab6373ac812842e",
24     "method": "GET",
25     "field": "status",
26     "paidValue": "PAID",
27     "hint": "Check status before retrying payment."
28   },
29   "links": {
30     "landingPage": "https://gwop.io",
31     "docs": "https://docs.gwop.io"
32   },
33   "paymentMethods": [
34     {
35       "id": "x402-base",
36       "kind": "x402",
37       "network": "eip155:8453",
38       "chain": "base",
39       "asset": {
40         "symbol": "USDC",
41         "decimals": 6,
42         "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
43       },
44       "payTo": "0xcFf8Dcf2e9562Ec4D77E387902BB52Ea18539215",
45       "amount": 1025000,
46       "amountDisplay": "1.025 USDC",
47       "paymentUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/base",
48       "recoverUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/base/recover"
49     },
50     {
51       "id": "x402-solana",
52       "kind": "x402",
53       "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
54       "chain": "solana",
55       "asset": {
56         "symbol": "USDC",
57         "decimals": 6,
58         "contract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
59       },
60       "payTo": "BL24KoQbSate4NkfbGoyqK3ts8ck8fjiXrM3K3BJ9Hpr",
61       "amount": 1025000,
62       "amountDisplay": "1.025 USDC",
63       "paymentUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/solana",
64       "recoverUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/solana/recover"
65     }
66   ]
67 }

Payment Methods

Open invoices include paymentMethods — the x402 payment rails scoped to this checkout session. Each method includes everything an agent needs to pay on a specific chain:

1 {
2   "id": "x402-base",
3   "kind": "x402",
4   "network": "eip155:8453",
5   "chain": "base",
6   "asset": {
7     "symbol": "USDC",
8     "decimals": 6,
9     "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
10   },
11   "payTo": "0xcFf8Dcf2e9562Ec4D77E387902BB52Ea18539215",
12   "amount": 1025000,
13   "amountDisplay": "1.025 USDC",
14   "paymentUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/base",
15   "recoverUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/base/recover"
16 }

Field	Description
`id`	Unique method identifier (`x402-base`, `x402-solana`)
`kind`	Payment protocol (`x402`)
`network`	CAIP-2 chain identifier
`chain`	Human-readable chain name (`base`, `solana`)
`asset`	Token details — symbol, decimals, contract address
`payTo`	Destination wallet address
`amount`	Amount in atomic units (same as invoice total)
`paymentUrl`	Session-scoped x402 endpoint — the agent pays here the same way it pays any x402 URL
`recoverUrl`	Recovery endpoint if payment was sent but not confirmed

Every checkout session includes x402 payment URLs for both Base (EVM) and Solana. The agent picks a chain, pays the session-scoped URL, and Gwop settles the checkout. These URLs are tied to the invoice session, not to a permanent merchant endpoint.

Pricing Breakdown

The public invoice includes a transparent fee breakdown:

Field	Description
`pricing.baseAmount`	The amount you requested
`pricing.gwopFee`	Gwop’s processing fee
`pricing.total`	Total the payer sends (= `amount.value`)

Status Check

The statusCheck object tells agents how to poll for payment confirmation:

1 // Agent-side polling pattern
2 const checkUrl = invoice.statusCheck.url;
3 const paidValue = invoice.statusCheck.paidValue; // "PAID"
4 
5 const poll = async () => {
6   const res = await fetch(checkUrl);
7   const data = await res.json();
8   return data[invoice.statusCheck.field] === paidValue;
9 };

Paid Invoice

After payment, the invoice gains settlement fields and loses paymentMethods:

1 {
2   "schemaVersion": "gwop.invoice.v4",
3   "id": "inv_b8d22e32425343958182533aa7994e35",
4   "status": "PAID",
5   "amount": {
6     "value": 1025,
7     "display": "0.001025 USDC",
8     "currency": "USDC",
9     "decimals": 6
10   },
11   "pricing": {
12     "baseAmount": 1000,
13     "gwopFee": 25,
14     "total": 1025
15   },
16   "expiresAt": "2026-04-08T03:39:04.601Z",
17   "createdAt": "2026-04-08T03:24:04.624Z",
18   "merchant": {
19     "name": "agentrouter",
20     "verified": true
21   },
22   "statusCheck": {
23     "url": "https://agents.gwop.io/v1/invoices/inv_b8d22e32...",
24     "method": "GET",
25     "field": "status",
26     "paidValue": "PAID",
27     "hint": "Check status before retrying payment."
28   },
29   "links": {
30     "landingPage": "https://gwop.io",
31     "docs": "https://docs.gwop.io"
32   },
33   "paidAt": "2026-04-08T03:24:17.508Z",
34   "paidAmount": 1025,
35   "paymentChain": "base",
36   "paymentChainCaip2": "eip155:8453",
37   "paidTxHash": "0x165de7bdf1e3803280388ef37683a2767ffecd098842feea7d03c39eb795e978",
38   "txUrl": "https://basescan.org/tx/0x165de7bdf1e3803280388ef37683a2767ffecd098842feea7d03c39eb795e978"
39 }

Field	Description
`paidAt`	Settlement timestamp
`paidAmount`	Amount settled in atomic USDC
`paymentChain`	`"base"` or `"solana"`
`paymentChainCaip2`	CAIP-2 chain identifier (`eip155:8453` for Base)
`paidTxHash`	On-chain transaction hash
`txUrl`	Block explorer link to the settlement transaction

paymentMethods is only present on OPEN invoices. Once an invoice is paid, expired, or canceled, this field is undefined.

Error: Invoice not found

1 import { ErrorCode, isGwopError } from "@gwop/sdk/errors";
2 
3 try {
4   await gwop.invoices.get({ id: "inv_doesnotexist" });
5 } catch (err) {
6   if (isGwopError(err, ErrorCode.InvoiceNotFound)) {
7     err.statusCode; // 404
8   }
9 }

Next step

Webhooks

Get notified when the agent pays — no polling required

Cancel Invoice

Cancel an open invoice before payment arrives