Skip to main content

​
GET /api/transactions/:id

Retrieves detailed information about a specific transaction. The transaction must belong to the authenticated user, otherwise a 404 error is returned.

​
Authentication

This endpoint requires authentication. Include a valid JWT token in the Authorization header: 
Authorization: Bearer <your_token>

​
Path Parameters

​
id
integer
required
The unique identifier of the transaction to retrieve.The transaction must belong to the authenticated user. If the transaction doesn’t exist or belongs to another user, a 404 error is returned.

​
Example Request

curl -X GET http://localhost:3001/api/transactions/42 \
  -H "Authorization: Bearer your_jwt_token"

​
Response

Returns a single transaction object with all details.
​
id
integer
The unique identifier for the transaction.
​
user_id
integer
The ID of the user who owns this transaction. Always matches the authenticated user’s ID.
​
transaction_type
string
The type of transaction: "Comprar" (Buy) or "Vender" (Sell).
​
amount_usd
number
The base amount in USD before commission.
​
commission_usd
number
The commission amount in USD that was applied to this transaction.Commission is calculated based on the amount:
  • 1−1 - 9.99: $0.80
  • 10−10 - 14.99: $1.00
  • 15−15 - 25: $1.40
  • Above 25:25: 1.40 + (0.08×(amount−0.08 × (amount - 25))
​
total_usd
number
The final amount in USD after applying commission.
  • For Comprar (Buy): amount_usd + commission_usd
  • For Vender (Sell): amount_usd - commission_usd
​
rate_bs
number
The exchange rate in Bolivares (Bs) per USD that was used for this transaction.
​
total_bs
number
The total amount in Bolivares, calculated as total_usd * rate_bs.
​
payment_reference
string
The unique payment reference number for this transaction.
​
status
string
The current status of the transaction. Common values:
  • "Pendiente" (Pending) - Transaction created but not yet processed
  • "Completada" (Completed) - Transaction successfully processed
  • "Cancelada" (Cancelled) - Transaction was cancelled
​
type_pay
string
The payment method used for this transaction.Common values:
  • “Pago Móvil” (Mobile payment)
  • “Transferencia” (Bank transfer)
  • “Zelle”
  • “PayPal”
​
recipient_account
string
The recipient account information associated with this transaction.Format varies by payment method:
  • Phone number for Pago Móvil (e.g., “0414-1234567”)
  • Email for Zelle/PayPal (e.g., “[email protected]”)
  • Account number for bank transfers (e.g., “0102-1234-5678-9012”)
​
created_at
datetime
The timestamp when the transaction was created (ISO 8601 format).
​
updated_at
datetime
The timestamp when the transaction was last updated (ISO 8601 format).

​
Success Response Example

{
  "id": 42,
  "user_id": 15,
  "transaction_type": "Comprar",
  "amount_usd": 50.00,
  "commission_usd": 3.40,
  "total_usd": 53.40,
  "rate_bs": 36.50,
  "total_bs": 1949.10,
  "payment_reference": "REF123456789",
  "status": "Pendiente",
  "type_pay": "Pago Móvil",
  "recipient_account": "0414-1234567",
  "created_at": "2026-03-03T14:20:00.000Z",
  "updated_at": "2026-03-03T14:20:00.000Z"
}

​
Error Responses

​
401 Unauthorized
object
Returned when the authentication token is missing, invalid, or expired.
{
  "message": "Authentication required"
}
​
404 Not Found
object
Returned when the transaction ID doesn’t exist or belongs to a different user.
{
  "message": "Transacción no encontrada"
}
This error is returned in two scenarios:
  1. The transaction ID doesn’t exist in the database
  2. The transaction exists but belongs to another user (security measure to prevent enumeration)
​
500 Internal Server Error
object
Returned when an unexpected server error occurs.
{
  "message": "Error del servidor"
}

​
Implementation Details

​
Security

The endpoint implements authorization at the database level. The query includes both the transaction ID and the authenticated user’s ID: 
SELECT * FROM transactions 
WHERE id = ? AND user_id = ?
This ensures:
  • Users can only access their own transactions
  • Transaction IDs of other users cannot be enumerated
  • Both missing and unauthorized transactions return the same 404 error (security best practice)

​
Use Cases

​
Transaction Details Page

Display complete transaction information on a dedicated details page: 
curl -X GET http://localhost:3001/api/transactions/42 \
  -H "Authorization: Bearer your_jwt_token"

​
Verify Transaction Status

Check if a transaction has been processed: 
// Poll for status updates
const checkTransactionStatus = async (transactionId) => {
  const response = await fetch(
    `http://localhost:3001/api/transactions/${transactionId}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const transaction = await response.json();
  return transaction.status;
};

// Usage
const status = await checkTransactionStatus(42);
if (status === 'Completada') {
  console.log('Transaction completed!');
}

​
Refresh Transaction Data

Fetch the latest data for a transaction after an update: 
// After status change or admin modification
const refreshTransaction = async (transactionId) => {
  const response = await fetch(
    `http://localhost:3001/api/transactions/${transactionId}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  if (response.ok) {
    return await response.json();
  } else if (response.status === 404) {
    throw new Error('Transaction not found');
  }
};

​
Generate Receipt

Use transaction details to generate a receipt or invoice: 
const generateReceipt = async (transactionId) => {
  const transaction = await fetch(
    `http://localhost:3001/api/transactions/${transactionId}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  ).then(r => r.json());
  
  return `
    Transaction Receipt
    -------------------
    ID: ${transaction.id}
    Type: ${transaction.transaction_type}
    Amount: $${transaction.amount_usd} USD
    Commission: $${transaction.commission_usd} USD
    Total: $${transaction.total_usd} USD (${transaction.total_bs} Bs)
    Rate: ${transaction.rate_bs} Bs/USD
    Reference: ${transaction.payment_reference}
    Status: ${transaction.status}
    Date: ${new Date(transaction.created_at).toLocaleString()}
  `;
};

Build docs developers (and LLMs) love

Get started for freeTalk to us