​
Overview

The getPaymentStatus function allows you to check the status of a payment transaction after it has been submitted. Use this to track whether a payment has been completed, is still pending, or has failed.

​
Function Signature

/**
 * Checks the status of a payment
 * @throws {Error} If the transaction ID is invalid
 */
declare function getPaymentStatus(options: GetPaymentStatusOptions): Promise<PaymentStatus>;

​
Parameters

​
GetPaymentStatusOptions

interface GetPaymentStatusOptions {
  /** Transaction hash from pay result */
  id: string;
  /** Must match testnet setting used in pay */
  testnet?: boolean;
}

​
Returns

​
PaymentStatus

interface PaymentStatus {
  /** Current status of the payment */
  status: "completed" | "pending" | "failed" | "not_found";
  /** Original transaction hash */
  id: string;
  /** Human-readable status message */
  message: string;
  /** Sender address (present for pending, completed, and failed) */
  sender?: string;
  /** Amount that was sent (present for completed transactions) */
  amount?: string;
  /** Address that received the payment (present for completed transactions) */
  recipient?: string;
  /** Error details (present for failed status) */
  error?: string;
}

​
Status Types

  • completed: Payment has been successfully processed and confirmed on the blockchain
  • pending: Payment is still being processed by the network
  • failed: Payment failed to process (funds are not transferred)
  • not_found: Transaction ID not found or invalid

​
Usage Example

import { pay, getPaymentStatus } from '@base-org/account';

async function sendAndTrackPayment() {
  try {
    // First, send a payment
    const payResult = await pay({
      amount: "10.50",
      to: "0x1234567890123456789012345678901234567890",
      testnet: false
    });

    if (payResult.success) {
      console.log("Payment submitted:", payResult.id);
      
      // Check payment status
      const status = await getPaymentStatus({
        id: payResult.id,
        testnet: false
      });
      
      console.log("Payment status:", status.status);
      console.log("Status message:", status.message);
      
      if (status.status === "completed") {
        console.log("Payment completed successfully!");
      } else if (status.status === "pending") {
        console.log("Payment is still processing...");
      } else if (status.status === "failed") {
        console.log("Payment failed:", status.message);
      }
    }
  } catch (error) {
    console.error("Error:", error);
  }
}

​
Polling for Status Updates

For pending payments, you may want to poll the status periodically:

async function pollPaymentStatus(transactionId: string, testnet: boolean = false) {
  const maxAttempts = 30;
  const pollInterval = 2000; // 2 seconds
  
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const status = await getPaymentStatus({
        id: transactionId,
        testnet
      });
      
      if (status.status === "completed") {
        console.log("Payment completed!");
        return status;
      } else if (status.status === "failed") {
        console.log("Payment failed:", status.message);
        return status;
      }
      
      // Still pending, wait before next check
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    } catch (error) {
      console.error("Error checking payment status:", error);
      break;
    }
  }
  
  console.log("Payment status check timed out");
  return null;
}

​
Error Handling

The getPaymentStatus function can throw errors for:

  • Invalid transaction ID format
  • Network connection issues
  • Transaction not found

Always wrap calls to getPaymentStatus in a try-catch block to handle these errors gracefully.