Transactions API

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.

Required URL Query Parameters:

startDate (string): Start date in YYYY-MM-DD format.
endDate (string): End date in YYYY-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.
shopperInteractions (string): A shopper interaction or a comma-separated list (e.g. ANY, Ecommerce, ContAuth, Moto, POS). Replaces the v1 source filter, which is not accepted in v2.
fundingSource (string): Funding source or a comma-separated list of funding sources. Accepted values: CREDIT, DEBIT, PREPAID.
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 100.
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. Keep going while hasMore is true. A cursor only works with the exact same filters that produced it. Changing any filter makes the cursor invalid.

# 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",
        "updatedAt": "2025-05-29T08:14:33.000Z",
        "pspReferenceId": "ZNS6KG5CXZL3JM65",
        "reference": "2RvOstypKrBgVMID",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null,
          "attributes": {
            "region": "Northeast",
            "tier": "Gold"
          }
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "store": {
          "id": "ST3296222002335LXVHVGG7WL",
          "referenceId": "reference-7741290835",
          "displayName": "Big Smile Boston - Newbury St"
        },
        "authorizedAmount": 21200,
        "currency": "USD",
        "surchargeAmount": 318,
        "tipAmount": 2000,
        "refundedAmount": 0,
        "paymentMethod": "mc",
        "paymentMethodVariant": "mc",
        "cardSummary": "0005",
        "fundingSource": "CREDIT",
        "shopperInteraction": "Ecommerce",
        "authCode": "048213",
        "status": "SETTLED",
        "paymentAttributes": {
          "invoice_id": "INV-2025-44817"
        }
      },
      {
        "createdAt": "2025-05-27T22:00:27.000Z",
        "updatedAt": "2025-05-27T22:00:27.000Z",
        "pspReferenceId": "X5N7KDMGPZBK6R65",
        "reference": "C0CoRvLO7eFe67Lc",
        "merchantAccount": {
          "businessName": "Big Smile Boston",
          "id": "MER4F5ZSPP48W",
          "referenceId": null,
          "attributes": {
            "region": "Northeast",
            "tier": "Gold"
          }
        },
        "organization": {
          "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
          "referenceId": null,
          "name": "Big Smile LLC"
        },
        "store": null,
        "authorizedAmount": 0,
        "currency": "USD",
        "surchargeAmount": null,
        "tipAmount": null,
        "refundedAmount": 0,
        "paymentMethod": "mc",
        "paymentMethodVariant": "mc",
        "cardSummary": "0005",
        "fundingSource": "CREDIT",
        "shopperInteraction": "Ecommerce",
        "authCode": null,
        "status": "AUTHORIZED",
        "paymentAttributes": {}
      }
    ],
    "nextCursor": "eyJjIjoiMjAyNS0xMS0zMFQyMzo1OTo1OS4wMDBaIiwiciI6IlBTUF9FWEFNUExFX1JFRiJ9",
    "hasMore": true
  }
}

Get a payment by PSP reference id (v2)

GET /api/v2/transactions/:pspReferenceId

Returns one payment. It has the same fields as a row from the cursor-based list, plus the fields below. All amounts are in minor units.

merchantSplitAmount (number or null): The merchant's share of the payment after fees. null until the split is known.
merchantRefundedAmount (number or null): The merchant's share of refunds.
tenantRefundedAmount (number or null): Your share of refunds.
transactionFee (number or null): The fee taken from the payment, which is authorizedAmount minus merchantSplitAmount. null until the split is known.
shopper (object or null): The shopper's firstName, lastName, and email from the checkout. null for payments without a checkout.
paymentEvents (array): The payment's events, newest first. Each event has a type, status, amount, currency, pspReferenceId, and createdAt.

If no payment matches, the API returns 404 with the errorCode PAYMENT_NOT_FOUND.

Response

{
  "status": "ok",
  "data": {
    "createdAt": "2025-05-27T21:50:01.000Z",
    "updatedAt": "2025-05-29T08:14:33.000Z",
    "pspReferenceId": "ZNS6KG5CXZL3JM65",
    "reference": "2RvOstypKrBgVMID",
    "authorizedAmount": 21200,
    "paymentMethod": "mc",
    "cardSummary": "0005",
    "fundingSource": "CREDIT",
    "status": "SETTLED",
    "shopperInteraction": "Ecommerce",
    "currency": "USD",
    "surchargeAmount": 318,
    "tipAmount": 2000,
    "refundedAmount": 0,
    "paymentMethodVariant": "mc",
    "authCode": "048213",
    "merchantAccount": {
      "businessName": "Big Smile Boston",
      "id": "MER4F5ZSPP48W",
      "referenceId": null,
      "attributes": {
        "region": "Northeast",
        "tier": "Gold"
      }
    },
    "organization": {
      "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
      "referenceId": null,
      "name": "Big Smile LLC"
    },
    "store": {
      "id": "ST3296222002335LXVHVGG7WL",
      "displayName": "Big Smile Boston - Newbury St",
      "referenceId": "reference-7741290835"
    },
    "paymentAttributes": {
      "invoice_id": "INV-2025-44817"
    },
    "merchantSplitAmount": 20564,
    "merchantRefundedAmount": null,
    "tenantRefundedAmount": null,
    "transactionFee": 636,
    "shopper": {
      "firstName": "John",
      "lastName": "Rocket",
      "email": "john@example.com"
    },
    "paymentEvents": [
      {
        "type": "SETTLEMENT",
        "status": "SETTLED",
        "amount": 21200,
        "currency": "USD",
        "pspReferenceId": "ZNS6KG5CXZL3JM65",
        "createdAt": "2025-05-28T06:00:00.000Z"
      },
      {
        "type": "AUTHORIZATION",
        "status": "AUTHORIZED",
        "amount": 21200,
        "currency": "USD",
        "pspReferenceId": "ZNS6KG5CXZL3JM65",
        "createdAt": "2025-05-27T21:50:01.000Z"
      }
    ]
  }
}

Get a payment by PSP reference id

GET /api/v1/transactions/:pspReferenceId

GET /api/v1/transactions/:pspReferenceId is deprecated

This endpoint will be removed after April 1, 2027. Use GET /api/v2/transactions/:pspReferenceId instead. Unlike this endpoint, it returns amounts in minor units, like the rest of the API. Responses from this endpoint include Deprecation, Sunset, and Link headers.

This endpoint returns amounts as decimals in the main currency unit. For example, 243.83 means $243.83. store.splitConfigurationGroup.refundSplitModel shows how refunds are split, and is one of deductAccordingToSplitRatio, deductFromLiableAccount, or deductFromOneBalanceAccount.

Response

{
  "status": "ok",
  "data": {
    "pspReferenceId": "DNCUFNNV2JQACYE3",
    "authorizedAmount": 243.83,
    "surchargeAmount": 4.88,
    "refundedAmount": 0,
    "merchantSplitAmount": 234.08,
    "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": 0,
    "tenantRefundedAmount": 0,
    "merchantAccount": {
      "businessName": "Big Smile Europe"
    },
    "store": {
      "displayName": "Big Smile Europe - Main",
      "splitConfigurationGroup": {
        "refundSplitModel": "deductAccordingToSplitRatio"
      }
    },
    "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": "CHARGEBACK",
        "status": "DISPUTED",
        "amount": 24383,
        "currency": "USD",
        "pspReferenceId": "CBK9F2K7PMNGZG65",
        "createdAt": "2024-05-06T10:12:00.000Z"
      },
      {
        "type": "SETTLEMENT",
        "status": "SETTLED",
        "amount": 243.83,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      },
      {
        "type": "AUTHORIZATION",
        "status": "AUTHORIZED",
        "amount": 243.83,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      }
    ]
  }
}

Payment events

The paymentEvents array lists the events recorded for the payment. Common type values include AUTHORIZATION, SETTLEMENT, REFUND, PARTIAL_REFUND, and the dispute-related types below.

Event type	Description
`NOTIFICATION_OF_FRAUD`	Fraud notification received from Adyen.
`REQUEST_FOR_INFORMATION`	Request for information received from Adyen.
`CHARGEBACK`	Chargeback against the payment. Each dispute has a separate event.

Fraud notifications and requests for information do not change the payment's status.
For dispute-related events, pspReferenceId identifies the dispute.