Get payout status

Fetch the current state of a payout this agent created.

Requires Authorization: Bearer <agent-jwt>.

GET/api/payouts/:payoutIdBearer agent-jwt↗

curl https://walletapi.fluxapay.xyz/api/payouts/po_abc123 \
  -H "Authorization: Bearer $AGENT_JWT"

200 OK:

{
  "payout": {
    "payoutId": "po_abc123",
    "displayStatus": "completed",
    "displayStatusExpiresAt": null,
    "txHash": "0xabc...def",
    "approvalUrl": "https://agentwallet.fluxapay.xyz/authorize-payout/po_abc123",
    "expiresAt": 1713340800,
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": "1000000",
    "currency": "USDC",
    "network": "base",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "mandateId": null,
    "bizId": "order_20260416_001",
    "description": "Refund for order #001",
    "agentId": "agent_001",
    "agentName": "My Agent",
    "failureReason": null,
    "createdAt": 1713254400,
    "executedAt": 1713254460
  }
}

displayStatus

displayStatus is the payout's outcome. Base your logic on this field.

displayStatus	Meaning	Final?	What to do
awaiting_approval	Waiting for the user to approve it in FluxA Wallet.	No	Show approvalUrl to the user and keep polling.
processing	Approved. The transfer is in progress.	No	Keep polling.
completed	The funds arrived. txHash is set.	Yes	Done.
failed	The payout didn't go through.	Yes	Create a new payout if you still need to pay.
rejected	The user declined the payout.	Yes	Don't retry without asking the user.
expired	The user didn't approve it before expiresAt.	Yes	Create a new payout (new payoutId) if still needed.

Treat any other value as processing. New outcome values may be added later.

While a payout is awaiting_approval, displayStatusExpiresAt gives the Unix time at which it becomes expired. Otherwise it is null.

Response fields

Field	Description
payoutId	Your payout ID.
displayStatus	Outcome. See the table above.
displayStatusExpiresAt	When an awaiting_approval payout expires (Unix seconds), or null.
txHash	On-chain transaction hash once the transfer is sent, or null.
approvalUrl	FluxA Wallet page where the user reviews this payout.
expiresAt	Approval deadline (Unix seconds).
toAddress	Destination address.
amount	Amount in atomic units.
currency	USDC.
network	base or base-sepolia.
assetAddress	USDC contract address.
mandateId	The mandate used for automatic approval, or null.
bizId	Your business reference, or null.
description	The memo, or null.
agentId	ID of the agent that created the payout.
agentName	Name of the agent that created the payout.
failureReason	Set only when displayStatus is failed: a short hint about why. Use it for logs only, not for program logic.
createdAt	Creation time (Unix seconds).
executedAt	When the transfer was sent (Unix seconds), or null.

Polling

Poll until displayStatus is completed, failed, rejected or expired. Leave a few seconds between calls.

Errors

HTTP	Body	Meaning
401	{ "error": "..." }	The agent JWT is missing, invalid or expired. A VC token returns { "error": "wrong_token_type" }.
404	{ "error": "Payout not found" }	No payout with this ID was created by this agent.