> ## Documentation Index
> Fetch the complete documentation index at: https://devdraft.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transaction Status

> Retrieve the current status and details of a payment intent transaction

The Get Transaction Status API allows you to check the current status of a previously created payment intent. This endpoint is essential for tracking payment progress, monitoring transaction state changes, and providing real-time updates to your users.

## Endpoint Details

<ParamField path="method" type="string">
  GET
</ParamField>

<ParamField path="url" type="string">
  `/api/v0/payment-intents/:transactionId/status`
</ParamField>

**Authentication**: Required (API Key & Secret)\
**Rate Limiting**: Standard rate limits apply

## Authentication

All requests require API key authentication using the following headers:

* `x-client-key`: Your application's client key
* `x-client-secret`: Your application's client secret

## Path Parameters

<ParamField path="transactionId" type="string" required>
  The transaction ID returned when creating the payment intent

  <br />

  **Example**: `"txn_01HZXK8M9N2P3Q4R5S6T7U8V9W"`
</ParamField>

## Transaction Statuses

The API returns one of the following status values:

| Status                 | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| **AWAITING\_FUNDS**    | Payment intent created, waiting for funds to be deposited                      |
| **IN\_REVIEW**         | Transaction is being reviewed for compliance or fraud prevention               |
| **FUNDS\_RECEIVED**    | Funds have been successfully received                                          |
| **PAYMENT\_SUBMITTED** | Payment has been submitted for processing on the blockchain or banking network |
| **PAYMENT\_PROCESSED** | Payment has been successfully processed and completed                          |
| **UNDELIVERABLE**      | Payment could not be delivered to the destination                              |
| **RETURNED**           | Payment was returned (e.g., invalid destination address)                       |
| **REFUNDED**           | Payment has been refunded to the sender                                        |
| **CANCELED**           | Transaction was canceled before completion                                     |
| **ERROR**              | An error occurred during processing                                            |
| **DISPUTED**           | Transaction is under dispute or investigation                                  |

## Request Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.devdraft.ai/api/v0/payment-intents/txn_01HZXK8M9N2P3Q4R5S6T7U8V9W/status" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET"
  ```

  ```javascript JavaScript/TypeScript theme={null}
  interface TransactionStatusResponse {
    id: string;
    bridge_transfer_id: string;
    status: string;
    amount: string;
    source: {
      payment_rail: string;
      currency: string;
    };
    destination: {
      payment_rail: string;
      currency: string;
      to_address?: string;
    };
    customer?: {
      first_name?: string;
      last_name?: string;
      email?: string;
      address?: string;
      phone_number?: string;
    };
    created_at: string;
    updated_at: string;
  }

  async function getTransactionStatus(
    transactionId: string
  ): Promise<TransactionStatusResponse> {
    const response = await fetch(
      `https://api.devdraft.ai/api/v0/payment-intents/${transactionId}/status`,
      {
        method: 'GET',
        headers: {
          'x-client-key': process.env.CLIENT_KEY!,
          'x-client-secret': process.env.CLIENT_SECRET!,
        },
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return response.json();
  }

  // Usage example
  const status = await getTransactionStatus('txn_01HZXK8M9N2P3Q4R5S6T7U8V9W');
  console.log(`Transaction status: ${status.status}`);
  ```

  ```python Python theme={null}
  import requests
  import os
  from typing import Dict, Any

  def get_transaction_status(transaction_id: str) -> Dict[str, Any]:
      """Get the status of a payment intent transaction"""

      url = f"https://api.devdraft.ai/api/v0/payment-intents/{transaction_id}/status"

      headers = {
          "x-client-key": os.getenv("CLIENT_KEY"),
          "x-client-secret": os.getenv("CLIENT_SECRET")
      }

      response = requests.get(url, headers=headers)
      response.raise_for_status()

      return response.json()

  # Usage example
  status = get_transaction_status("txn_01HZXK8M9N2P3Q4R5S6T7U8V9W")
  print(f"Transaction status: {status['status']}")
  ```

  ```php PHP theme={null}
  <?php
  class TransactionStatus {
      private $clientKey;
      private $clientSecret;
      private $baseUrl;

      public function __construct($clientKey, $clientSecret, $baseUrl = 'https://api.devdraft.ai') {
          $this->clientKey = $clientKey;
          $this->clientSecret = $clientSecret;
          $this->baseUrl = $baseUrl;
      }

      public function getStatus($transactionId) {
          $url = $this->baseUrl . '/api/v0/payment-intents/' . $transactionId . '/status';

          $headers = [
              'x-client-key: ' . $this->clientKey,
              'x-client-secret: ' . $this->clientSecret
          ];

          $ch = curl_init();
          curl_setopt($ch, CURLOPT_URL, $url);
          curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

          $response = curl_exec($ch);
          $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
          curl_close($ch);

          if ($httpCode === 200) {
              return json_decode($response, true);
          } else {
              throw new Exception('Failed to get transaction status: ' . $response);
          }
      }
  }

  // Usage example
  $transactionStatus = new TransactionStatus('your-client-key', 'your-client-secret');
  $status = $transactionStatus->getStatus('txn_01HZXK8M9N2P3Q4R5S6T7U8V9W');
  echo "Transaction status: " . $status['status'];
  ?>
  ```
</CodeGroup>

## Response Format

### Success Response (200 OK)

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "txn_01HZXK8M9N2P3Q4R5S6T7U8V9W",
    "bridge_transfer_id": "transfer_abc123xyz456",
    "status": "PAYMENT_PROCESSED",
    "amount": "100.00",
    "source": {
      "payment_rail": "ethereum",
      "currency": "usdc"
    },
    "destination": {
      "payment_rail": "base",
      "currency": "eurc",
      "to_address": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8e1"
    },
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "address": "123 Main St, New York, NY 10001",
      "phone_number": "+1-555-123-4567"
    },
    "created_at": "2023-07-01T12:00:00.000Z",
    "updated_at": "2023-07-01T12:30:00.000Z"
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="id" type="string">
  Unique transaction identifier in our database
</ResponseField>

<ResponseField name="bridge_transfer_id" type="string">
  External bridge service transfer ID for tracking
</ResponseField>

<ResponseField name="status" type="string">
  Current transaction status (see status table above)
</ResponseField>

<ResponseField name="amount" type="string">
  Payment amount in the source currency
</ResponseField>

<ResponseField name="source" type="object">
  Source payment details

  <Expandable title="properties">
    <ResponseField name="payment_rail" type="string">
      Source payment rail or blockchain network
    </ResponseField>

    <ResponseField name="currency" type="string">
      Source currency code
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="destination" type="object">
  Destination payment details

  <Expandable title="properties">
    <ResponseField name="payment_rail" type="string">
      Destination payment rail or blockchain network
    </ResponseField>

    <ResponseField name="currency" type="string">
      Destination currency code
    </ResponseField>

    <ResponseField name="to_address" type="string">
      Destination wallet address (if applicable)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer" type="object">
  Customer information (if provided during payment intent creation)

  <Expandable title="properties">
    <ResponseField name="first_name" type="string">
      Customer's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Customer's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Customer's email address
    </ResponseField>

    <ResponseField name="address" type="string">
      Customer's physical address
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Customer's phone number
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Transaction creation timestamp (ISO 8601 format)
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp (ISO 8601 format)
</ResponseField>

## Error Responses

<CodeGroup>
  ```json 401 Unauthorized theme={null}
  {
    "statusCode": 401,
    "message": "Unauthorized - Invalid API credentials",
    "error": "Unauthorized"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "statusCode": 404,
    "message": "Transaction not found or access denied",
    "error": "Not Found"
  }
  ```
</CodeGroup>

## Use Cases

### Real-Time Status Updates

Implement polling or webhook-based status monitoring to provide real-time updates to your users:

<CodeGroup>
  ```javascript Status Polling theme={null}
  class PaymentStatusMonitor {
    constructor(clientKey, clientSecret) {
      this.clientKey = clientKey;
      this.clientSecret = clientSecret;
      this.pollInterval = null;
    }

  async pollStatus(transactionId, callback, intervalMs = 5000) {
  // Initial check
  const initialStatus = await this.checkStatus(transactionId);
  callback(initialStatus);

      // Continue polling if not in terminal state
      if (!this.isTerminalStatus(initialStatus.status)) {
        this.pollInterval = setInterval(async () => {
          const status = await this.checkStatus(transactionId);
          callback(status);

          if (this.isTerminalStatus(status.status)) {
            this.stopPolling();
          }
        }, intervalMs);
      }

  }

  async checkStatus(transactionId) {
  const response = await fetch(
  `https://api.devdraft.ai/api/v0/payment-intents/${transactionId}/status`,
  {
  headers: {
  'x-client-key': this.clientKey,
  'x-client-secret': this.clientSecret,
  },
  }
  );

      if (!response.ok) {
        throw new Error(`Failed to check status: ${response.status}`);
      }

      return response.json();

  }

  isTerminalStatus(status) {
  return [
  'PAYMENT_PROCESSED',
  'UNDELIVERABLE',
  'RETURNED',
  'REFUNDED',
  'CANCELED',
  'ERROR',
  ].includes(status);
  }

  stopPolling() {
  if (this.pollInterval) {
  clearInterval(this.pollInterval);
  this.pollInterval = null;
  }
  }
  }

  // Usage
  const monitor = new PaymentStatusMonitor('your-key', 'your-secret');

  monitor.pollStatus('txn_01HZXK8M9N2P3Q4R5S6T7U8V9W', (status) => {
  console.log(`Current status: ${status.status}`);

  if (status.status === 'PAYMENT_PROCESSED') {
  console.log('Payment completed successfully!');
  } else if (status.status === 'ERROR') {
  console.error('Payment failed:', status);
  }
  });

  ```
</CodeGroup>

## Best Practices

### Polling Strategy

<Tip>
  **Recommended Polling Intervals:** - Initial 5 minutes: Poll every 5 seconds -
  After 5 minutes: Poll every 30 seconds - After 30 minutes: Poll every 2
  minutes - Always stop polling when reaching a terminal status
</Tip>

### Error Handling

Always implement robust error handling:

```javascript theme={null}
async function checkStatusWithRetry(transactionId, maxRetries = 3) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await getTransactionStatus(transactionId);
    } catch (error) {
      lastError = error;
      if (error.status === 404) {
        // Transaction not found - don't retry
        throw error;
      }
      // Wait before retry (exponential backoff)
      await new Promise((resolve) =>
        setTimeout(resolve, 1000 * Math.pow(2, i))
      );
    }
  }

  throw lastError;
}
```

### Status Notifications

Notify users about important status changes:

```javascript theme={null}
const NOTIFY_STATUSES = [
  "FUNDS_RECEIVED",
  "PAYMENT_PROCESSED",
  "ERROR",
  "UNDELIVERABLE",
  "RETURNED",
  "REFUNDED",
];

function shouldNotifyUser(status) {
  return NOTIFY_STATUSES.includes(status);
}

async function monitorAndNotify(transactionId, userEmail) {
  let previousStatus = null;

  const checkStatus = async () => {
    const statusData = await getTransactionStatus(transactionId);

    if (
      statusData.status !== previousStatus &&
      shouldNotifyUser(statusData.status)
    ) {
      await sendNotification(userEmail, statusData);
    }

    previousStatus = statusData.status;
    return statusData;
  };

  return checkStatus;
}
```

## Support

For additional support or questions about the Get Transaction Status API:

1. Check our API status page for known issues
2. Review the error codes and messages in your responses
3. Contact our support team with your transaction ID for specific issues
4. Use our testing environment to validate integrations before going live

<Info>
  For more information, see: - [Create Stablecoin Payment
  Intent](/docs/developers/payment-intents/create-stablecoin-payment-intent) -
  [Create Bank Payment
  Intent](/docs/developers/payment-intents/create-bank-payment-intent) - [Webhooks
  Overview](/docs/developers/webhooks/overview) - [API Authentication
  Guide](/docs/developers/home/api-request-authentication)
</Info>