Skip to main content

​
Transactions

A Transaction represents a card spend event on the payment network. Transactions flow through multiple stages from initial authorization to final settlement.

​
Transaction Lifecycle

When a card is used at a merchant, the payment network sends an authorization request. Proxy evaluates the request against policies and available funds.
Card Used → Authorization Request → Policy Check → Approve/Decline
  • Approved: A hold is placed on funds equal to the authorized amount
  • Declined: No hold is placed; transaction is rejected

​
Transaction Types

TypeDescription
authorizationInitial approval request from merchant
settlementFinal capture of authorized amount
refundCredit returned to cardholder
reversalAuthorization cancelled before settlement
force_captureSettlement without prior authorization

​
Transaction Statuses

StatusDescription
pendingAuthorization approved, awaiting settlement
settledTransaction completed and posted
declinedAuthorization was rejected
reversedAuthorization cancelled; hold released

​
Transaction Fields

FieldTypeDescription
idstringUnique transaction identifier
cardIdstringCard used for transaction
customerIdstringOwner of the card
agentIdstringAgent that initiated the spend
intentIdstringMatched intent (if any)
amountnumberTransaction amount in cents
currencystringCurrency code (e.g., USD)
statusstringCurrent transaction status
typestringTransaction type
merchantobjectMerchant details
createdAtstringTimestamp of transaction creation

​
Merchant Object

FieldTypeDescription
namestringMerchant name
mccstringMerchant Category Code
citystringMerchant city
countrystringMerchant country code
categorystringHuman-readable category

​
Intent Matching

When a transaction occurs, Proxy automatically matches it against pending intents for the card.

​
Matching Rules

Amount Tolerance

Transaction amount must be within the configured tolerance of the expected amount (default: +/- 10%)

Merchant Match

Fuzzy matching on merchant name if expectedMerchant was specified

MCC Match

MCC must be in expectedMccs list if specified

Time Window

Transaction must occur before intent expiration

​
Match Outcomes

StatusDescription
matchedTransaction matched all intent criteria
mismatchedTransaction occurred but didn’t match expectations
expiredIntent expired before any transaction

​
Viewing Transactions

​
List Transactions

curl https://api.useproxy.ai/v1/transactions \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "transactions": [
    {
      "id": "txn_abc123",
      "cardId": "card_xyz789",
      "amount": 4250,
      "currency": "USD",
      "status": "settled",
      "type": "settlement",
      "merchant": {
        "name": "AMAZON.COM",
        "mcc": "5942",
        "city": "SEATTLE",
        "country": "US",
        "category": "Book Stores"
      },
      "intentId": "int_def456",
      "intentStatus": "matched",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "cursor": "next_page_token"
}

​
Filter by Card

curl "https://api.useproxy.ai/v1/transactions?cardId=card_xyz789" \
  -H "Authorization: Bearer your_api_key"

​
Filter by Status

curl "https://api.useproxy.ai/v1/transactions?status=pending" \
  -H "Authorization: Bearer your_api_key"

​
Filter by Date Range

curl "https://api.useproxy.ai/v1/transactions?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer your_api_key"

​
Get Single Transaction

curl https://api.useproxy.ai/v1/transactions/txn_abc123 \
  -H "Authorization: Bearer your_api_key"

​
Transaction Webhooks

Subscribe to transaction events for real-time notifications:
EventDescription
transaction.createdNew authorization approved or declined
transaction.updatedAuthorization modified (incremental auth, partial reversal)
transaction.settledTransaction settled and posted
transaction.declinedAuthorization was declined

​
Webhook Payload

{
  "id": "evt_abc123",
  "type": "transaction.created",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "transactionId": "txn_xyz789",
    "cardId": "card_abc123",
    "amount": 4250,
    "currency": "USD",
    "status": "pending",
    "type": "authorization",
    "merchant": {
      "name": "AMAZON.COM",
      "mcc": "5942"
    }
  }
}

​
Decline Reasons

When a transaction is declined, the response includes a reason:
ReasonDescription
insufficient_fundsNot enough available balance
card_spending_limit_exceededExceeds card limit
blocked_merchantMerchant is blocked
blocked_mccMCC is restricted
card_frozenCard is temporarily frozen
card_canceledCard has been closed
policy_violationTransaction violates policy rules
no_valid_intentNo matching intent found (when required)

​
Adding a Memo

Attach a note to a transaction for record-keeping: 
curl -X PATCH https://api.useproxy.ai/v1/transactions/txn_abc123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "memo": "Office supplies for Q1 project"
  }'

​
Uploading Receipts

Attach a receipt to a transaction: 
curl -X PUT https://api.useproxy.ai/v1/transactions/txn_abc123/receipt \
  -H "Authorization: Bearer your_api_key" \
  -F "receipt=@receipt.pdf"
Retrieve a receipt: 
curl https://api.useproxy.ai/v1/transactions/txn_abc123/receipt \
  -H "Authorization: Bearer your_api_key" \
  -o receipt.pdf

​
Next Steps

Intents

Declare purchase intents

Disputes

Handle transaction disputes

Balances

Understand fund management

Webhooks

Get real-time notifications