Payments

Payments are two-step: initiate records the intent in the database, process submits the atomic group to Algorand and waits for confirmation. The two-step design lets you decouple validation from on-chain submission.

Initiate

POST/paymentsJWT

Field	Type
invoiceId	string	required — unique per payment
agentId	string (uuid)	required
poolId	string (uuid)	required
merchantId	string	required — registered in MerchantRegistry
amountUsdCents	integer	required — e.g. 100 = $1.00
network	"mainnet" \| "testnet"	optional — default: testnet

// 201 Created
{
  "id": "uuid",
  "invoiceId": "inv-001",
  "status": "pending",
  "amountUsdCents": 100,
  "network": "testnet",
  "gasSponsored": true
}

Process

Submits the 3-transaction atomic group to Algorand. Blocks until confirmed (≈4 seconds on testnet). On success, status becomes settled and the configured webhook fires.

POST/payments/:paymentId/processJWT

{
  "id": "uuid",
  "status": "settled",
  "algoTxnId": "JYHEQ...",
  "blockRound": 62111040,
  "confirmedAt": "2026-04-05T03:54:38Z",
  "gasFeeAlgo": "0.005",
  "gasSponsored": true
}

Gas sponsorship: The LogicSig account pays all 5 transaction fees (5000 microALGO). The paying agent's ALGO balance is never touched.

Query

GET/payments/:paymentIdJWT

GET/payments/invoice/:invoiceIdJWT

GET/paymentsAll payments for authenticated userJWT

Query param	Values
status	pending · processing · settled · failed
limit	default 20
offset	default 0

GET/payments/agent/:agentIdJWT

Payment statuses

Status	Meaning
pending	Created, awaiting process call
processing	On-chain submission in progress
settled	Confirmed on Algorand
failed	Submission failed — see timeline for reason