Transactions API

Get all payments (paginated)

Optional URL Query Parameters:

status (string): Status or a comma-separated list of statuses.
pspReferenceId (string): The unique reference ID for the payment service provider.
paymentMethod (string): A single payment method.
source (string, deprecated): Legacy filter — a source or a comma-separated list of sources (e.g. ECOMMERCE, TERMINAL). Internally mapped to shopperInteraction values. Use shopperInteraction instead. If both are provided, shopperInteraction takes precedence.
shopperInteraction (string): A shopper interaction or a comma-separated list (e.g. ECOMMERCE, TERMINAL).
shopperEmail (string): Shopper's email address.
merchantAccountId (string): Selected merchant account id.
organizationId (string): Selected organization id.
startDate (string): Start date in 'y-MM-dd' format.
endDate (string): End date in 'y-MM-dd' format, inclusive of the day.
pageSize (number): Number of records to return, max 1000.
pageIndex (number): Page index beginning with 0.

GET /api/v1/transactions

GET /api/v1/transactions is deprecated

This list endpoint will be removed after October 1, 2026. New integrations should use the cursor-based endpoint (GET /api/v2/transactions), which paginates in constant time and supports unbounded depth. Deprecated responses include a Deprecation header. The single-transaction endpoint GET /api/v1/transactions/:pspReferenceId is not affected.

Response

{
  "status": "ok",
  "data": {
    "rows": [
      {
        "createdAt": "2025-05-27T21:50:01.000Z",
        "pspReferenceId": "ZNS6KG5CXZL3JM65",
        "reference": "2RvOstypKrBgVMID",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 21200,
        "paymentMethod": "mc",
        "cardSummary": "0005",
        "source": "ECOMMERCE",
        "status": "SETTLED"
      },
      {
        "createdAt": "2025-05-27T22:00:27.000Z",
        "pspReferenceId": "X5N7KDMGPZBK6R65",
        "reference": "C0CoRvLO7eFe67Lc",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 0,
        "paymentMethod": "mc",
        "cardSummary": "0005",
        "source": "ECOMMERCE",
        "status": "AUTHORIZED"
      },
      {
        "createdAt": "2025-05-27T21:48:34.000Z",
        "pspReferenceId": "N5C78NK78XLH5K75",
        "reference": "B5lrmIRBsskGnJkJ",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 0,
        "paymentMethod": "mc",
        "cardSummary": "0005",
        "source": "ECOMMERCE",
        "status": "AUTHORIZED"
      }
    ],
    "pagination": {
      "pageIndex": 0,
      "pageSize": 3,
      "pageCount": 34,
      "total": 100,
      "hasPrevPage": false,
      "hasNextPage": true
    }
  }
}

Get all payments (cursor-based)

Uses cursor pagination for constant-time paging on large datasets. Does not return a total count and requires both startDate and endDate. Rows have the same shape as v1.

Required URL Query Parameters:

startDate (string): Start date in 'y-MM-dd' format.
endDate (string): End date in 'y-MM-dd' format, inclusive of the day.

Optional URL Query Parameters:

status (string): Status or a comma-separated list of statuses.
pspReferenceId (string): The unique reference ID for the payment service provider.
paymentMethod (string): A single payment method.
shopperInteraction (string): A shopper interaction or a comma-separated list (e.g. ECOMMERCE, TERMINAL). Replaces the v1 source filter, which is not accepted in v2.
shopperEmail (string): Shopper's email address.
merchantAccountId (string): Selected merchant account id.
organizationId (string): Selected organization id.
pageSize (number): Number of records to return, max 1000.
cursor (string): Opaque cursor returned as nextCursor in the previous response. Omit for the first page.

GET /api/v2/transactions

Paging through results

Request the first page without a cursor, then pass the previous response's nextCursor as the cursor query parameter. Continue while hasMore is true. Cursors are opaque and valid only for the exact same set of filters that produced them — changing any filter invalidates the cursor.

# First page
GET /api/v2/transactions?startDate=2025-11-01&endDate=2025-11-30&pageSize=100

# Next page
GET /api/v2/transactions?startDate=2025-11-01&endDate=2025-11-30&pageSize=100&cursor=eyJjIjoi...

Response


  "status": "ok",
  "data": {
    "rows": [
      {
        "createdAt": "2025-05-27T21:50:01.000Z",
        "pspReferenceId": "ZNS6KG5CXZL3JM65",
        "reference": "2RvOstypKrBgVMID",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 21200,
        "paymentMethod": "mc",
        "cardSummary": "0005",
        "source": "ECOMMERCE",
        "status": "SETTLED"
      },
      {
        "createdAt": "2025-05-27T22:00:27.000Z",
        "pspReferenceId": "X5N7KDMGPZBK6R65",
        "reference": "C0CoRvLO7eFe67Lc",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 0,
        "paymentMethod": "mc",
        "cardSummary": "0005",
        "source": "ECOMMERCE",
        "status": "AUTHORIZED"
      }
    ],
    "nextCursor": "eyJjIjoiMjAyNS0xMS0zMFQyMzo1OTo1OS4wMDBaIiwiciI6IlBTUF9FWEFNUExFX1JFRiJ9",
    "hasMore": true
  }
}

Get a payment by PSP reference id

GET /api/v1/transactions/:pspReferenceId

Response

{
  "status": "ok",
  "data": {
    "pspReferenceId": "xxx232",
    "authorizedAmount": 24383,
    "surchargeAmount": 488,
    "refundedAmount": 0,
    "merchantSplitAmount": 23408,
    "tipAmount": null,
    "currency": "USD",
    "status": "DISPUTED",
    "paymentMethod": "mc",
    "paymentMethodVariant": "mcsuperpremiumdebit",
    "cardSummary": "1226",
    // Deprecated, use split amounts of the payment instead
    "splitSettingsFixed": 0,
    // Deprecated, use split amounts of the payment instead
    "splitSettingsPercentage": 300,
    "updatedAt": "2024-05-05T08:31:25.398Z",
    "createdAt": "2024-05-05T08:31:25.398Z",
    "reference": "cce9f7d6-f21f-45d1-b4a5-079cbf3581f2",
    "merchantAccountId": "0f922ad3-a5ca-4213-9d1b-f943e95831c4",
    "organizationId": "bf368afb-ed57-4345-a04a-7c7213431a99",
    "source": "ECOMMERCE",
    "merchantRefundedAmount": null,
    "tenantRefundedAmount": null,
    "merchantAccount": {
      "businessName": "Big Smile Europe",
      "splitConfigurationGroup": {
        "refundSplitModel": "REVERSE_PAYMENT_SPLIT"
      }
    },
    "organization": {
      "name": "Big Smile LLC"
    },
    "checkout": {
      "shopperId": null,
      "shopperFirstName": null,
      "shopperLastName": null,
      "shopperEmail": "K-gk3DmjiJl-xABMFb23k@example.com",
      "checkoutAttributes": [
        {
          "name": "INVOICE_ID",
          "value": "rwR42JRurM_WLua4qxoi4"
        }
      ]
    },
    "paymentEvents": [
      {
        "type": "SETTLEMENT",
        "status": "SETTLED",
        "amount": 24383,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      },
      {
        "type": "AUTHORIZATION",
        "status": "AUTHORIZED",
        "amount": 24383,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      }
    ]
  }
}