SUsumup
Transactions

List transactions

Changed on

Lists transaction history for the merchant, with optional filters for payment type, status, and date range. The response contains the current page in items and pagination query strings in links.

To request another page, use the query string from the relevant link's href with this history endpoint. Use changes_since when retrieving transactions modified since a previous synchronization, including transactions created earlier whose status has changed.

get/v2.1/merchants/{merchant_code}/transactions/history

Request

  • Base URL
    https://api.sumup.com
  • URL
    https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions/history
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://api.sumup.com/authorize
      Token URL: https://api.sumup.com/token scopes: transactions.history, transactions.read

Path parameters

merchant_codestring required
Example:MH4H92C7

Short unique identifier for the merchant.

Query parameters

transaction_codestring
Example:TEENSK4W2K

Retrieves the transaction resource with the specified transaction code.

order'ascending' | 'descending'

Sort direction for the transaction history. Use ascending or descending; the default is ascending.

limitinteger
Example:10

Maximum number of transactions per page. Must be a positive integer. Defaults to 10 when omitted; a page can contain fewer results.

users[]string[]

Filters transactions by user email. For multiple values, repeat the query parameter, for example users[]=first@example.com&users[]=second@example.com.

[
  "merchant@example.com"
]
statuses[]string[]

Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example statuses[]=SUCCESSFUL&statuses[]=REFUNDED.

[
  "SUCCESSFUL",
  "REFUNDED"
]
payment_types[]PaymentType[]

Filters the returned results by the specified list of payment types used for the transactions.

[
  "ECOM",
  "POS"
]
entry_modes[]EntryMode[]

Filters the returned results by the specified list of entry modes.

[
  "CUSTOMER_ENTRY",
  "CHIP"
]
types[]string[]

Filters the returned results by the specified list of transaction types.

[
  "PAYMENT",
  "REFUND"
]
changes_sincestring date-time
Example:2019-08-28T09:00:00Z

Filters the results by the latest modification time of resources and returns only transactions that are modified at or after the specified timestamp (in ISO8601 format).

newest_timestring date-time
Example:2019-08-29T09:00:00Z

Filters the results by the creation time of resources and returns only transactions that are created before the specified timestamp (in ISO8601 format).

newest_refstring
Example:090df9bf-93b7-40f1-8181-fbdb236568a1

Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over newest_time when both are provided.

oldest_timestring date-time
Example:2019-08-28T09:00:00Z

Filters the results by the creation time of resources and returns only transactions that are created at or after the specified timestamp (in ISO8601 format).

oldest_refstring
Example:090df9bf-93b7-40f1-8181-fbdb236568a1

Pagination reference that returns results after the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over oldest_time when both are provided.

Response

Returns a page of transaction history items.

Example response

{
  "items": [
    {
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "user": "merchant@example.com",
      "type": "PAYMENT",
      "payout_date": "2019-08-28",
      "payout_type": "BANK_ACCOUNT",
      "refunded_amount": 0
    }
  ],
  "links": []
}

Changes

  • fddb4ef1245aRevision changes
    • warning

      added the new SUMUP enum value to the /// response property for the response status

  • 0f66b0a52002Revision changes
    • warning

      added the new BANCOMAT enum value to the /// response property for the response status

    • info

      removed the BGN enum value from the /// response property for the response status