Get Transaction Status

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

string

GET

string

/api/v0/payment-intents/:transactionId/status

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

string

required

The transaction ID returned when creating the payment intent
Example: "txn_01HZXK8M9N2P3Q4R5S6T7U8V9W"

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

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"

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}`);

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
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'];
?>

Response Format

Success Response (200 OK)

{
  "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"
}

Response Fields

string

Unique transaction identifier in our database

string

External bridge service transfer ID for tracking

string

Current transaction status (see status table above)

string

Payment amount in the source currency

object

Source payment details

Show properties

string

Source payment rail or blockchain network

string

Source currency code

object

Destination payment details

Show properties

string

Destination payment rail or blockchain network

string

Destination currency code

string

Destination wallet address (if applicable)

object

Customer information (if provided during payment intent creation)

Show properties

string

Customer’s first name

string

Customer’s last name

string

Customer’s email address

string

Customer’s physical address

string

Customer’s phone number

string

Transaction creation timestamp (ISO 8601 format)

string

Last update timestamp (ISO 8601 format)

Error Responses

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid API credentials",
  "error": "Unauthorized"
}

{
  "statusCode": 404,
  "message": "Transaction not found or access denied",
  "error": "Not Found"
}

Use Cases

Real-Time Status Updates

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

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);
}
});

Best Practices

Polling Strategy

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

Error Handling

Always implement robust error handling:

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:

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:

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

For more information, see: - Create Stablecoin Payment Intent - Create Bank Payment Intent - Webhooks Overview - API Authentication Guide

Home

Payment Intents

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Path Parameters

Transaction Statuses

Request Examples

Response Format

Success Response (200 OK)

Response Fields

Error Responses

Use Cases

Real-Time Status Updates

Best Practices

Polling Strategy

Error Handling

Status Notifications

Support

​Endpoint Details

​Authentication

​Path Parameters

​Transaction Statuses

​Request Examples

​Response Format

​Success Response (200 OK)

​Response Fields

​Error Responses

​Use Cases

​Real-Time Status Updates

​Best Practices

​Polling Strategy

​Error Handling

​Status Notifications

​Support

Endpoint Details

Authentication

Path Parameters

Transaction Statuses

Request Examples

Response Format

Success Response (200 OK)

Response Fields

Error Responses

Use Cases

Real-Time Status Updates

Best Practices

Polling Strategy

Error Handling

Status Notifications

Support