Transactions

Overview

The Transactions endpoints allow you to retrieve transaction and payment data. Transactions represent payment events that occur when agents make payments using payment intents. Each transaction includes details such as amount, merchant, date, status, and associated payment intent information. Transactions are read-only - they are automatically created when payments are processed.

Get Transactions

Retrieves a list of transactions based on filter criteria. You can filter, sort, and paginate the results using query parameters.

Query Parameters

Use the filter query parameter to filter, sort, and paginate results. The filter should be a JSON object passed as a URL-encoded string.

Filter Options

The filter object supports the following properties:

Where Clause Examples

Common filter conditions for the where clause:

Example Requests

Get all posted transactions for a user in a date range:

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: 'posted',
    date: {
      between: ['2024-01-01', '2024-12-31']
    }
  },
  order: 'date DESC',
  limit: 50
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Expenses?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const transactions = await response.json();

Get transactions with receipts included:

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: {inq: ['posted', 'pending']}
  },
  include: ['receipts'],
  order: 'date DESC',
  limit: 100
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Expenses?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const transactions = await response.json();

Get transactions by category and amount:

const filter = {
  where: {
    ownerId: 'user-id-123',
    category: 'Travel',
    amount: {gte: 100}
  },
  order: 'amount DESC'
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Expenses?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const transactions = await response.json();

Response

[
  {
    "id": "transaction-id-123",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "status": "posted",
    "date": "2024-01-15T10:30:00.000Z",
    "amount": 45.50,
    "currency": "USD",
    "amountInLocalCurrency": 45.50,
    "settlementAmount": 45.50,
    "settlementCurrency": "USD",
    "merchantName": "Starbucks",
    "category": "Meals",
    "allocationId": "allocation-id-456",
    "purpose": "Coffee meeting",
    "receiptRequired": true,
    "isSplit": false,
    "created": "2024-01-15T10:30:00.000Z",
    "modified": "2024-01-15T10:30:00.000Z"
  },
  {
    "id": "transaction-id-789",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "status": "pending",
    "date": "2024-01-16T14:20:00.000Z",
    "amount": 250.00,
    "currency": "USD",
    "amountInLocalCurrency": 250.00,
    "settlementAmount": 250.00,
    "settlementCurrency": "USD",
    "merchantName": "United Airlines",
    "category": "Travel",
    "allocationId": "allocation-id-789",
    "purpose": "Business trip",
    "receiptRequired": true,
    "isSplit": false,
    "created": "2024-01-16T14:20:00.000Z",
    "modified": "2024-01-16T14:20:00.000Z"
  }
]

Get Transaction by ID

Retrieves detailed information about a specific transaction by its ID.

Path Parameters

Query Parameters

Example Request

Using cURL:

curl -X GET "https://sandbox.custodia-tech.com/md/api/Expenses/transaction-id-123?filter=%7B%22include%22%3A%5B%22receipts%22%5D%7D" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const transactionId = 'transaction-id-123';

const filter = {
  include: ['receipts', 'transaction']
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Expenses/${transactionId}?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const transaction = await response.json();

Response

  {
    "id": "transaction-id-123",
  "ownerId": "user-id-123",
  "companyId": "company-id-123",
  "status": "posted",
  "date": "2024-01-15T10:30:00.000Z",
  "amount": 45.50,
  "currency": "USD",
  "amountInLocalCurrency": 45.50,
  "settlementAmount": 45.50,
  "settlementCurrency": "USD",
  "merchantName": "Starbucks",
  "merchantCategory": "Restaurants",
  "category": "Meals",
  "allocationId": "allocation-id-456",
  "budgetAllocationId": "budget-allocation-id",
  "purpose": "Coffee meeting",
  "receiptRequired": true,
  "isSplit": false,
  "costCenterId": "cost-center-id",
  "glAccountCode": "6001",
      "receipts": [
        {
          "id": "receipt-id-123",
          "expenseId": "transaction-id-123",
      "mimeType": "image/jpeg",
      "url": "https://storage.example.com/receipts/receipt-id-123.jpg"
    }
  ],
  "created": "2024-01-15T10:30:00.000Z",
  "modified": "2024-01-15T10:30:00.000Z"
}

Error Responses

All endpoints may return the following error responses: