Recharge a card

Add funds to an existing active card. Recharge uses the same two-step x402 flow as issuance: initiate, sign the payment with a mandate, then complete.

CLI

fluxa-wallet card recharge --id card_7Hq2LmX9pRt4 --amount 10.00 --mandate <mandate_id>
# continue the same recharge later (card is inferred):
fluxa-wallet card recharge --request-id <pendingRequestId> --mandate <mandate_id>

You need a signed USDC mandate whose remaining budget covers amountUsd + feeUsd.

---

Initiate a recharge

POST/api/v2/cards/{cardId}/recharge/initiateBearer agent-vc

curl -X POST https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/recharge/initiate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_VC" \
  -d '{ "amountUsd": "10.00" }'

Field	Type	Required	Description
amountUsd	string	yes	Amount to add, in USD with up to two decimals. On 400 invalid_amount the error message states the allowed range. The resulting balance must also stay within the per-card balance cap.

Response 200:

{
  "pendingRequestId": "9d3e1f7a-2c4b-4a8e-b6d0-1e5f7a9c3b21",
  "status": "pending_payment",
  "amountUsd": "10.00",
  "feeUsd": "0.00",
  "totalUsd": "10.00",
  "expiresAt": "2026-10-27T11:05:00.000Z",
  "paymentRequest": { "x402Version": 1, "accepts": [ { "…": "…" } ] },
  "paymentLinkId": "…",
  "checkoutUrl": null
}

feeUsd is the recharge fee you will pay on top of amountUsd. Sign paymentRequest with your mandate as described in Sign the payment with a mandate.

Only one recharge can be open per card. If one is already in progress you get 409 recharge_in_progress with details.pendingRequestId; continue that request instead.

---

Complete a recharge

POST/api/v2/cards/{cardId}/recharge/completeBearer agent-vc

curl -X POST https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/recharge/complete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_VC" \
  -d '{
    "pendingRequestId": "9d3e1f7a-2c4b-4a8e-b6d0-1e5f7a9c3b21",
    "paymentPayloadB64": "<xPaymentB64>"
  }'

Response 200 — funds added:

{
  "success": true,
  "card": { "id": "card_7Hq2LmX9pRt4", "remainingAmountUsd": "28.40", "…": "see Card object" },
  "recharge": { "amountUsd": "10.00", "feeUsd": "0.00" }
}

Response 202 — payment received, funds still being added:

{
  "success": false,
  "status": "payment_submitted",
  "pendingRequestId": "9d3e1f7a-2c4b-4a8e-b6d0-1e5f7a9c3b21",
  "message": "Payment submitted; recharge will complete automatically once settlement is confirmed"
}

On 202, do not pay again. Poll GET /api/v2/cards/requests/{pendingRequestId} until status is completed, then read the balance.

---

Errors

Status	code	What to do
400	invalid_amount	Use an amount within the range in the error message.
400	card_balance_limit_exceeded	The card would exceed its balance cap. Use a smaller amount.
400	pending_request_card_mismatch	The request belongs to another card. Use the matching cardId.
400	recharge_not_supported	This card cannot be recharged.
404	card_not_found, pending_request_not_found	Check the IDs.
409	card_not_active	Only active cards can be recharged.
409	recharge_in_progress	Continue the request in details.pendingRequestId.
409	pending_request_invalid_status	The request is no longer payable. Check its status.
410	pending_request_expired	The payment window passed. Start a new recharge.

See Errors for the full list.