Get Payment Status

GET /v1/payments/:requestId — check the current status of a payment request.

Get Payment Status

GET/v1/payments/:requestId

Retrieve the current status of a previously submitted payment request. Use this endpoint to poll for resolution when a payment is routed through AI verification or human review.

Path Parameters

Parameter	Type	Required	Description
requestId	string	Required	The unique request identifier returned by POST /v1/payments.

Response

{
  "requestId": "req_7f2a9b",
  "status": "approved",
  "txHash": "0x1234567890abcdef...",
  "reason": null
}

Parameter	Type	Required	Description
requestId	string	Required	The request identifier (echoed back).
status	string	Required	Current status of the payment. See status values below.
txHash	string	Optional	On-chain transaction hash. Present when status is "approved".
pollUrl	string	Optional	Relative URL for continued polling. Present when status is still pending.
estimatedResolutionMs	number	Optional	Estimated remaining time in milliseconds. Updated as the request progresses.
reason	string	Optional	Human-readable explanation. Present when status is "rejected".

Status Values

Status	Description
`approved`	The payment was executed on-chain. `txHash` is available. This is a terminal state.
`pending_review`	The payment is awaiting AI consensus or human approval. Continue polling until resolved.
`rejected`	The payment was denied by AI verification, policy enforcement, or the owner. `reason` explains why. This is a terminal state.

Polling Strategy

When a payment returns pending_review, poll at reasonable intervals until you receive a terminal status (approved or rejected).

Recommended polling intervals:

AI scan path: Poll every 5 seconds for up to 60 seconds. Most AI scan decisions complete within 30 seconds.
Human review path: Poll every 30-60 seconds. These depend on the owner reviewing in the dashboard and may take minutes to hours.

async function waitForResolution(relayerUrl: string, requestId: string): Promise<PaymentResult> {
  const url = `${relayerUrl}/v1/payments/${requestId}`;
 
  while (true) {
    const response = await fetch(url);
    const result = await response.json();
 
    if (result.status === 'approved' || result.status === 'rejected') {
      return result;
    }
 
    // Wait 5 seconds before next poll
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

For production bots, use poll() with appropriate backoff intervals. Poll every 5 seconds for AI scan paths (~30s resolution) and every 30-60 seconds for human review paths.

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	No payment request exists with this `requestId`.
`429`	`RATE_LIMITED`	Too many status checks. Check the `Retry-After` header.

Example

curl

curl https://relay.axonfi.xyz/v1/payments/req_7f2a9b

Response (approved)

{
  "requestId": "req_7f2a9b",
  "status": "approved",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Response (pending review)

{
  "requestId": "req_7f2a9b",
  "status": "pending_review",
  "pollUrl": "/v1/payments/req_7f2a9b",
  "estimatedResolutionMs": 25000
}

Response (rejected)

{
  "requestId": "req_7f2a9b",
  "status": "rejected",
  "reason": "AI verification failed: behavioral anomaly detected. Transaction amount 3x higher than 30-day average for this bot."
}