Skip to main content

​
Transactions

Transactions represent card purchases. They’re created automatically when a card is used and can be enriched with metadata, receipts, and notes.

​
Transaction Lifecycle

authorized → completed    (purchase settled)
authorized → reversed     (authorization voided)
authorized → declined     (rejected by network or policy)

​
List Transactions

Get all transactions for your organization: 
curl https://api.ledger.so/v1/transactions \
  -H "Api-Key: $API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "id": "txn_abc123",
      "cardId": "card_xyz",
      "userId": "user_123",
      "agentId": "agent_456",
      "amount": 2500,
      "currency": "USD",
      "merchantName": "DOORDASH",
      "merchantCategory": "5812",
      "status": "completed",
      "createdAt": 1703520000000
    }
  ],
  "hasMore": false
}

​
Filter Options

ParameterDescription
cardIdFilter by card
userIdFilter by user
agentIdFilter by agent
statusFilter by status (authorized, completed, reversed, declined)
limitResults per page (max 100)
cursorPagination cursor
curl "https://api.ledger.so/v1/transactions?userId=user_123&status=completed&limit=10" \
  -H "Api-Key: $API_KEY"

​
Get Transaction

curl https://api.ledger.so/v1/transactions/txn_abc123 \
  -H "Api-Key: $API_KEY"

{
  "object": "transaction",
  "id": "txn_abc123",
  "cardId": "card_xyz",
  "userId": "user_123",
  "agentId": "agent_456",
  "amount": 2500,
  "currency": "USD",
  "merchantName": "DOORDASH",
  "merchantCategory": "5812",
  "merchantCategoryName": "Restaurants",
  "status": "completed",
  "authorizationCode": "123456",
  "notes": null,
  "tags": [],
  "category": null,
  "receiptUrl": null,
  "intentId": "int_matched",
  "createdAt": 1703520000000,
  "settledAt": 1703523600000
}

​
Update Transaction Metadata

Add notes, tags, or categorize transactions: 
curl -X PATCH https://api.ledger.so/v1/transactions/txn_abc123 \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Team lunch order",
    "tags": ["food", "team-expense"],
    "category": "meals"
  }'
FieldDescription
notesFree-form text notes
tagsArray of string tags
categoryCategory label

​
Receipts

​
Upload Receipt (File)

curl -X PUT https://api.ledger.so/v1/transactions/txn_abc123/receipt \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]"

​
Upload Receipt (URL)

curl -X PUT https://api.ledger.so/v1/transactions/txn_abc123/receipt \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/receipts/order-123.pdf"
  }'

​
Get Receipt

curl https://api.ledger.so/v1/transactions/txn_abc123/receipt \
  -H "Api-Key: $API_KEY"

​
Delete Receipt

curl -X DELETE https://api.ledger.so/v1/transactions/txn_abc123/receipt \
  -H "Api-Key: $API_KEY"

​
Transaction Status

StatusDescription
authorizedPending, funds held
completedSettled, funds charged
reversedAuthorization voided
declinedRejected (policy, funds, network)

​
Merchant Categories

Transactions include MCC (Merchant Category Code) data:
FieldDescription
merchantCategory4-digit MCC code
merchantCategoryNameHuman-readable category
Common categories:
  • 5411 - Grocery Stores
  • 5812 - Restaurants
  • 5814 - Fast Food
  • 5942 - Book Stores
  • 7011 - Hotels

​
Card Transactions

Get transactions for a specific card: 
curl https://api.ledger.so/v1/cards/card_xyz/transactions \
  -H "Api-Key: $API_KEY"

​
Webhooks

EventDescription
transaction.authorizedNew authorization
transaction.completedTransaction settled
transaction.reversedAuthorization voided
transaction.declinedTransaction rejected

Disputes

Learn how to dispute transactions