Skip to main content

Transactions API

Read the payment activity of your program's cards. See Transaction Lifecycle for statuses and stages.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

GET /transactions​

List transactions across your program. Filters: userId, cardId, status, from, to. Paginated with limit and cursor.

// Response
{
  "data": [
    {
      "id": "txn_c410",
      "cardId": "card_3b7c",
      "userId": "usr_9f4c",
      "status": "settled",
      "amount": "42.90",
      "currency": "USDC",
      "merchant": {
        "name": "AIRLINE TICKETS LTD",
        "category": "airlines",
        "country": "US"
      },
      "authorizedAt": "2026-07-18T09:12:44Z",
      "settledAt": "2026-07-19T02:03:10Z",
      "settlementTxHash": "0x9c2f…e11a"
    }
  ],
  "nextCursor": null
}

settlementTxHash links every settled payment to its verifiable on-chain settlement.

GET /transactions/{id}​

Retrieve a single transaction with its full event history (authorization, capture, settlement, refunds).

GET /transactions/dispute-reasons​

List the accepted dispute reason codes.

// Response
{
  "data": [
    { "code": "fraud", "label": "Unauthorized transaction" },
    { "code": "not_received", "label": "Goods or services not received" },
    { "code": "duplicate", "label": "Duplicate charge" },
    { "code": "amount_differs", "label": "Charged amount differs" }
  ]
}

POST /transactions/{id}/disputes​

Open a dispute for a settled transaction. Available within 60 days of settlement.

// Request
{ "reason": "duplicate", "comment": "Charged twice for the same order." }

// Response
{ "id": "dsp_11ba", "transactionId": "txn_c410", "status": "open" }

Dispute progress is delivered through transaction.updated webhooks with the embedded dispute object.

Last updated on