Payment status


GET /api/v1/payment/reference/{reference_id}

Reads one payment. This is the call to make before fulfilling an order: a webhook tells you something changed, this endpoint tells you the current state from your own server. The read is served from the database; it makes no RPC call and never changes the payment.

Headers: API-Key.

Request


curl https://<your-site>/api/v1/payment/reference/c80f5363-0397-4761-aa1a-3155c3a21470 \
  -H "API-Key: 811b12035f0dfa8ffd62296df3c98b27"

Parameter	In	Constraints
`reference_id`	path	Version 4 UUID from create payment.

Response

200 OK


{
  "referenceID": "c80f5363-0397-4761-aa1a-3155c3a21470",
  "invoiceID": "INV-0090",
  "customerID": "1234",
  "customerEmail": "[email protected]",
  "amountInUSD": "50.000000",
  "paymentState": "FILLED",
  "currency": "USDC",
  "network": "SOLANA",
  "filledAmount": "50",
  "filledAmountInUSD": "50.000000",
  "depositAddress": "4Nd1mYw9zqXxq2Vb7Lr8KfJ3sT6uHc1pQe9RaBwDgF2h",
  "confirmationCurrent": 1,
  "confirmationRequired": 1,
  "expiresAt": "2026-09-23T06:53:42.419Z",
  "createdAt": "2026-09-22T06:53:42.419Z",
  "merchantName": "Project One",
  "testMode": false
}

Field	Type	Meaning
`referenceID`	string	The payment’s reference id.
`invoiceID`	string	Your `invoiceID` from creation, or `""`.
`customerID`	string	Your `customerID` from creation.
`customerEmail`	string	The customer’s current email address.
`amountInUSD`	string	Requested amount, six decimals.
`paymentState`	string	`OPEN`, `PARTIALLY_FILLED`, `FILLED`, `OVER_FILLED` or `CANCELLED`. See Payment states.
`currency`	string	The selected currency code, or the restricting currency from creation, or `""` when neither is set.
`network`	string	The selected chain code, or the restricting chain from creation, or `""`.
`filledAmount`	string	Confirmed amount in units of the selected currency (`"0"` until a currency is selected). Not padded to the currency’s decimals.
`filledAmountInUSD`	string	Confirmed amount in USD, six decimals. Includes transfers in any currency credited to this payment.
`depositAddress`	string	The receiving address for the selected currency (the token account for SPL tokens), the deposit account when a chain is selected but no currency yet, or `""`.
`confirmationCurrent`	integer	The lowest confirmation count across the payment’s non-orphaned transfers. `0` with no transfers.
`confirmationRequired`	integer	The selected or restricting chain’s confirmation threshold. `0` when no chain is set.
`expiresAt`	string or null	ISO 8601 expiry.
`createdAt`	string	ISO 8601 creation time.
`merchantName`	string	The project name.
`testMode`	boolean	`true` on a testnet install.

Amounts are strings. Do not parse amountInUSD or filledAmountInUSD into a binary floating-point number before comparing them.

Errors

Status	`code`	Cause
400	`BAD_REQUEST`	`reference_id` is not a version 4 UUID.
401	`UNAUTHORIZED`	Invalid API key.
404	`NOT_FOUND`	No payment with this reference id in the key’s project.
429	`RATE_LIMITED`	Per-key limit exhausted.
503	`UNAVAILABLE`	Rate-limit setting invalid or Redis unreachable.

Polling

Webhooks are the intended way to learn about changes; poll this endpoint as a fallback or to confirm a webhook. The per-key limit is 300 requests per minute by default across every keyed endpoint, so polling many open payments every few seconds will exhaust it. The hosted checkout page polls its own public endpoint, which is limited per IP address and does not count against your key.