Get Invoice | Gwop Docs

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