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:

Using JavaScript (fetch):

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:

Using JavaScript (fetch):

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:

Using JavaScript (fetch):

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

Transaction Simulation

Simulates a card authorization in sandbox. Use this to test whether a card, merchant, amount, and activity rules produce the expected authorization outcome before relying on live card spend.

Request Body

The request body contains a details object describing the transaction to simulate:

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/TransactionSimulations/execute \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "details": {
      "cardId": "bedfff5b-4537-4c60-8541-d35fe570e149",
      "merchantId": "d4b1ff86-b8a0-4f98-b6c4-9a08b0cfbf58",
      "amount": 2.99,
      "postTransaction": true,
      "refundAmount": null,
      "j5Ind": null,
      "delay": 2000
    }
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/TransactionSimulations/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    details: {
      cardId: 'bedfff5b-4537-4c60-8541-d35fe570e149',
      merchantId: 'd4b1ff86-b8a0-4f98-b6c4-9a08b0cfbf58',
      amount: 2.99,
      postTransaction: true,
      refundAmount: null,
      j5Ind: null,
      delay: 2000
    }
  })
});

const simulation = await response.json();

Response

On success the API returns the simulated authorization result as JSON. The exact response fields can vary by card issuer and simulation path. Example shape (ids and token values are illustrative):

{
  "type": "authorization",
  "state": "PENDING",
  "identifier": "33503",
  "token": "019e65f1-1ab0-7df0-8b2f-2cf8811cfef9",
  "business_token": "4f3c0916-bee8-4f68-8d3d-ad808400a351",
  "acting_user_token": "3fb782c0-476c-4e7f-af36-2a2e608a80ec",
  "card_token": "0998a733-639c-4522-be92-c0bf14369dbb",
  "card_product_token": "c71ddf2f-292f-4502-a2e9-f8f0f38ede11",
  "is_recurring": false,
  "cardholder_impact": true,
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 58139.16,
    "available_balance": 0,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -2.99
  },
  "gpa_order": {
    "token": "5b7e422d-2d40-43fc-b23d-92c0ab4985b9",
    "amount": 2.99,
    "state": "PENDING",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "funding_source_token": "**********e5b3",
    "currency_code": "USD"
  },
  "duration": 510,
  "created_time": "2026-05-26T20:19:20Z",
  "request_amount": 2.99,
  "amount": 2.99,
  "currency_code": "USD",
  "approval_code": "253861",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "network": "DISCOVER",
  "card": {
    "last_four": "3360",
    "metadata": {
      "our_ccid": "bedfff5b-4537-4c60-8541-d35fe570e149",
      "our_uid": "e1c93ff3-d089-49f4-8b78-445ad884168e",
      "our_cid": "7332ad13-d460-457d-b73f-0e1681f060fc"
    }
  },
  "card_acceptor": {
    "mid": "863332000492496",
    "mcc": "5734",
    "name": "ORACLE IRELAND",
    "city": "St. Petersburg",
    "state": "CA",
    "zip": "33705",
    "country": "USA"
  },
  "is_installment": false
}

Transaction Webhooks

Custodia can push real-time notifications to your HTTPS endpoint when card transactions are created or updated. Use webhooks to react to authorizations, declines, and status changes without polling the Transactions API.

Event Types

Delivery

• Events are delivered as POST requests with a JSON body and Content-Type: application/json.
• Delivery is at-least-once; retries include attempt and redelivery fields so you can detect duplicates.
• Use the top-level id as an idempotency key.
• Return any 2xx response to acknowledge receipt.

Example Payload

{
  "id": "ba31a2aa-dfac-4e6b-9623-6cf2dc0f9b5d",
  "eventType": "transaction.created",
  "eventTimestamp": "2026-06-23T00:58:36.389Z",
  "transaction": {
    "id": "UL3X9mprW785qrVkG5-FA",
    "companyId": "7332ad13-d460-457d-b73f-0e1681f060fc",
    "ownerId": "2d9f5599-80f9-4623-8e9f-d49e490addd6",
    "cardId": "fadaacdb-c08c-401e-b6ab-ceb9a1e782ec",
    "status": "declined",
    "source": "card",
    "classification": "business",
    "amount": 0,
    "authorized": 0,
    "credit": 0,
    "failed": 7,
    "currency": "USD",
    "originalAmount": 7,
    "originalCurrency": "USD",
    "conversionRate": 1,
    "merchantName": "LINKEDIN-529*9486234",
    "mcc": "5968",
    "merchantId": "13f05d5d-7ff4-4179-9b1a-035cabb0e079",
    "timestamp": "2026-06-23T00:58:35.000Z",
    "user_timestamp": "2026-06-23T00:58:35.000Z",
    "cardIssuerId": "CardIssuer",
    "externalId": "BmUBM0gIe12f296SNUD87",
    "journalType": "authorization",
    "successful": false,
    "description": "activity/no-match,expense-policy/tenant"
  },
  "attempt": 1,
  "redelivery": false
}

Webhook Payload Fields

Each delivery wraps transaction data in a standard envelope. The transaction object includes only the allowed fields below: no other transaction properties are sent.

Envelope Fields

Transaction Fields

Error Responses

All endpoints may return the following error responses: