/api/qmail/raida/payments/claim

GET POST

Download payment coins from the locker attached to a received email, save them to the wallet's Grade folder, and run the standard grade pass. Requires consensus across at least 13 of 25 RAIDA servers.

GET http://localhost:8081/api/qmail/raida/payments/claim?email_id={email_id}&wallet_path=Default

Description

If the email's payment record is found and the underlying locker still holds coins, this endpoint downloads them, drops them in <wallet>/Grade, then runs the wallet's standard grade pipeline (which moves coins into Bank or Fracked depending on RAIDA verdicts). The DB payment_status is updated to 1 (claimed) on success and 2 (failed) on failure.

If payment_status is already 1, the endpoint short-circuits and returns status: "already_claimed".

Inspect first

Call db/payments/get first to confirm can_retry is true.

Parameters

Param	Type	Required	Description
`email_id`	32-char hex GUID	Yes	The email containing the payment.
`wallet_path`	string	Yes	Wallet to deposit the claimed coins into.

Response

Successful claim

{
  "command": "payments-claim",
  "success": true,
  "email_id": "0c4f8e2a91b34d57a76e1d2c3b4a5968",
  "status": "claimed",
  "message": "Payment claimed successfully",
  "status_persisted": true,
  "coins_found": 3,
  "coins_saved": 3,
  "total_value": 30,
  "graded_to_bank": 3,
  "graded_to_fracked": 0
}

Already claimed

{
  "command": "payments-claim",
  "success": true,
  "email_id": "0c4f8e2a91b34d57a76e1d2c3b4a5968",
  "status": "already_claimed",
  "message": "Payment was already claimed successfully"
}

Errors

HTTP	Message
400	Missing 'email_id' parameter
400	Invalid email_id format (expected 32 hex chars)
400	No payment attached to this email
404	Email not found / Wallet not found
500	Cannot resolve wallet path / Transport not initialized / Database error
500	Payment claim failed - locker may be empty or network error (extra fields: `raida_success`, `detail`)

Example

# GET — easy browser/devtool testing
curl "http://localhost:8081/api/qmail/raida/payments/claim?email_id=0c4f8e2a91b34d57a76e1d2c3b4a5968&wallet_path=Default"

# Canonical POST
curl -X POST "http://localhost:8081/api/qmail/raida/payments/claim" \
  -d "email_id=0c4f8e2a91b34d57a76e1d2c3b4a5968" \
  -d "wallet_path=Default"

/api/qmail/db/payments/get — Check before claiming.
/api/qmail/raida/locker/import-credentials — Different flow: imports identity credentials from a locker into the Mail folder rather than Grade.