The transaction status endpoint allows you to check the current status and details of a transaction using the payment reference ID from the widget session.

​
GET /v1/transactions/:transactionId/status

Check the status of a transaction using the payment reference ID.

​
Request Headers

X-API-Key: your_api_key_here

​
Path Parameters

ParameterTypeRequiredDescription
transactionIdstringYesPayment reference ID (sessionId)

​
Response

{
    "transactionId": "364d2ed2X3jpd4b299240077fbf23c20",
    "paymentStatus": "COMPLETED",
    "transactionStatus": "COMPLETED",
    "transactionHash": "0xede81a00c118566bfa793d48ecbcaa3d2497b7f25a142f0a408e5bbffda86a15",
    "amount": "21.5",
    "currency": "USD",
    "convertedAmount": "20.26",
    "convertedCurrency": "USDC",
    "paymentMethod": "card",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8E9A7",
    "blockchain": "polygon",
    "chainId": 80002,
    "fees": {
        "USD": {
            "partnerFee": "0.32",
            "totalFee": "1.19",
            "networkFee": "0.01",
            "transactionFee": "0.86"
        }
    },
    "createdAt": "2025-10-27T11:28:37Z"
}
If widget session was created, but transaction is not initiated, we return this response: 
{
    "transactionId": "364d2ed2X3jpd4b299240077fbf23c20",
    "transactionStatus": "REQUESTED"
}
Please notice that we cache the requested transaction for 3 days.
After this period if transaction is not started, 404 status is returned

​
Response Fields

FieldTypeDescription
transactionIdstringUnique transaction identifier
paymentStatusstringPayment processing status (e.g., “COMPLETED”)
transactionStatusstringBlockchain transaction status (e.g., “COMPLETED”)
transactionHashstringBlockchain transaction hash
amountstringAmount paid in fiat (with 18 decimal precision)
currencystringFiat currency used
convertedAmountstringAmount received in crypto (with 18 decimal precision)
convertedCurrencystringCryptocurrency purchased
paymentMethodstringPayment method used (e.g., “card”)
destinationAddressstringRecipient wallet address
blockchainstringBlockchain network name
chainIdnumberNumeric blockchain identifier
feesobjectFee breakdown with currency-specific amounts
createdAtstringCreate datetime

​
Transaction Status Values

StatusDescription
pendingTransaction initiated, awaiting payment
processingPayment received, processing transaction
completedTransaction successful, crypto delivered
failedTransaction failed

​
Integration Examples

requestExample.js
const response = await axios.get(
    '{{base_url}}/v1/transactions/ffcaa6d5aZ2Qc305927a482e18362b72/status',
    {
        headers: {
            'X-API-Key': 'your_api_key_here'
        }
    }
);

console.log(`Transaction status: ${response.data}`);

​
Polling for Status Updates

If you’re not using webhooks, you can poll this endpoint to check for status updates: 
async function pollTransactionStatus(transactionId, apiKey) {
  const checkStatus = async () => {
    try {
      const response = await fetch(
        `{{base_url}}/v1/transactions/${transactionId}/status`,
        {
          headers: { 'X-API-Key': apiKey }
        }
      );
      
      const data = await response.json();
      console.log(`Status: ${data.status}`);
      
      // Stop polling if transaction is final
      if (['completed', 'failed', 'cancelled'].includes(data.status)) {
        clearInterval(interval);
        return data;
      }
    } catch (error) {
      console.error('Error checking status:', error);
    }
  };
  
  // Check immediately
  checkStatus();
  
  // Then check every 5 seconds
  const interval = setInterval(checkStatus, 5000);
  
  // Stop after 30 minutes
  setTimeout(() => clearInterval(interval), 30 * 60 * 1000);
}
Polling should be used sparingly. We recommend using webhooks for real-time updates instead of polling. If you must poll, limit requests to once every 5 seconds.

​
Error Responses

​
Transaction Not Found

{
    "code": "NOT_FOUND",
    "message": "Record not found"
}

​
Invalid Transaction ID

{
    "code": "INVALID_REQUEST",
    "message": "Invalid Transaction ID"
}

​
Best Practices

  1. Store transaction references securely for future lookups
  2. Use webhooks instead of polling when possible
  3. Handle all status types in your integration
  4. Display blockchain info to users for completed transactions
  5. Implement proper error handling for failed lookups
The transaction reference is the same as the sessionId returned when creating a widget session. Store this value to track transactions throughout their lifecycle.